tca-js 0.3.0 → 0.3.1

package/dist/api.js

@@ -10,11 +10,11 @@ const listener_1 = require("./listener");
 const media_1 = require("./media");
 const message_1 = require("./message");
 const proto_1 = require("./proto");
-/** Mốc "mới nhất" khi đọc lịch sử — lớn hơn mọi `index` (µs). */
+/** "Latest" cursor for reading history — greater than any `index` (µs). */
 const NEWEST = 9999999999999999n;
 /**
- * Một phiên TikTok đã đăng nhập — tạo bằng `new TikTok().login(credentials)`.
- * Mọi lệnh đi thẳng HTTP/WS tới TikTok bằng cookie, không cần trình duyệt.
+ * A logged-in TikTok session — create with `new TikTok().login(credentials)`.
+ * All calls go directly over HTTP/WS to TikTok using cookies, no browser needed.
  */
 class API {
     ctx;
@@ -30,44 +30,44 @@ class API {
     getOwnId() {
         return this.ctx.ownId;
     }
-    /** Cookie hiện tại — lưu lại để lần sau `login` không cần quét QR. */
+    /** Current cookies — save them so the next `login` needs no QR scan. */
     getCookies() {
         return [...this.ctx.cookies].map(([name, value]) => ({ name, value }));
     }
     getContext() {
         return { deviceId: this.ctx.deviceId, userAgent: this.ctx.userAgent };
     }
-    /** Phiên còn sống không — gọi định kỳ để phát hiện hết hạn sớm. */
+    /** Whether the session is still alive — call periodically to detect expiry early. */
     async isAlive() {
         return (await fetchAccount(this.ctx).catch(() => null)) !== null;
     }
-    // ─── Hộp thư ─────────────────────────────────────────────────────────────
-    /** Hội thoại gần đây + tin mới nhất của chúng, lật trang bằng `cursor`. */
+    // ─── Inbox ─────────────────────────────────────────────────────────────────
+    /** Recent conversations + their latest messages, paginated with `cursor`. */
     async getConversations(cursor = '0') {
         const body = await this.ctx.im('/v2/message/get_by_user_init', constants_1.Cmd.GetMessagesByUserInit, new proto_1.Writer().int(1, BigInt(cursor)).finish());
         return {
             messages: body.msgs(1).map((m) => (0, message_1.parseMessage)(m, this.ctx.ownId)),
             conversations: body.msgs(2).map((m) => (0, message_1.parseConversation)(m, this.ctx.ownId)),
-            // Con trỏ = số hội thoại đã lấy (0, 10, 20…) — trường 4; trường 3 là mốc thời gian, không dùng để lật.
+            // Cursor = number of conversations fetched so far (0, 10, 20…) — field 4; field 3 is a timestamp, not used for paging.
             cursor: body.id(4),
             hasMore: body.num(5) === 1,
         };
     }
-    /** Tin của một hội thoại, mới nhất trước. Đọc tiếp tin cũ hơn: `before = <index của tin cũ nhất>`. */
+    /** Messages of a conversation, newest first. For older messages: `before = <index of oldest message>`. */
     async getMessages(conv, opts = {}) {
         const limit = Math.min(Math.max(opts.limit ?? 20, 1), 50);
         const body = await this.ctx.im('/v1/message/get_by_conversation', constants_1.Cmd.GetMessagesByConversation, new proto_1.Writer()
             .bytes(1, conv.conversationId)
             .int(2, constants_1.ConversationType.OneToOne)
             .int(3, BigInt(conv.conversationShortId))
-            .int(4, 1) // hướng: cũ hơn mốc
+            .int(4, 1) // direction: older than cursor
             .int(5, opts.before ? BigInt(opts.before) : NEWEST)
             .int(6, limit)
             .finish());
         const messages = body.msgs(1).map((m) => (0, message_1.parseMessage)(m, this.ctx.ownId));
         return { messages, hasMore: messages.length >= limit };
     }
-    /** Hồ sơ người dùng theo uid (tên hiển thị, @username, ảnh đại diện). */
+    /** User profiles by uid (display name, @username, avatar). */
     async getUsers(uids) {
         if (uids.length === 0)
             return [];
@@ -90,8 +90,8 @@ class API {
         }));
     }
     /**
-     * Tải ảnh đại diện (thử lần lượt các link, bỏ heic). Không gửi cookie / Referer: CDN ảnh khác miền và
-     * link đã có chữ ký. `null` nếu không link nào tải được.
+     * Download an avatar (tries each URL in turn, skips heic). No cookie / Referer sent: the image CDN is cross-origin and
+     * URLs are already signed. `null` if no URL could be downloaded.
      */
     async downloadAvatar(user) {
         for (const url of user.avatars) {
@@ -107,7 +107,7 @@ class API {
         }
         return null;
     }
-    /** Đánh dấu đã đọc tới tin `msg`. */
+    /** Mark as read up to message `msg`. */
     async markRead(msg) {
         await this.ctx.im('/v3/conversation/mark_read', constants_1.Cmd.MarkRead, new proto_1.Writer()
             .bytes(1, msg.conversationId)
@@ -117,14 +117,14 @@ class API {
             .int(11, 4)
             .finish(), constants_1.MARK_READ_BODY_FIELD);
     }
-    // ─── Gửi ──────────────────────────────────────────────────────────────────
-    /** Gửi tin chữ vào hội thoại (thường là `msg` vừa nhận — nó mang sẵn mã hội thoại). */
+    // ─── Send ─────────────────────────────────────────────────────────────────
+    /** Send a text message to a conversation (usually the just-received `msg` — it carries the conversation ids). */
     async sendMessage(conv, text) {
         const cid = (0, node_crypto_1.randomUUID)();
         await this.send(conv, cid, constants_1.MessageType.Text, JSON.stringify({ aweType: 0, text }), null);
         return { clientMessageId: cid };
     }
-    /** Gửi một ảnh: tải lên kho riêng tư (được mã hoá) rồi gửi tin ảnh. */
+    /** Send an image: upload to the private (encrypted) store, then send an image message. */
     async sendImage(conv, image) {
         const up = await this.media.upload(image);
         const cid = (0, node_crypto_1.randomUUID)();
@@ -159,9 +159,9 @@ class API {
         return { clientMessageId: cid };
     }
     /**
-     * Đặt reaction CỦA MÌNH trên một tin — như TikTok Web, mỗi người một reaction: `emoji` mới thay cái cũ,
-     * `null` = gỡ. Truyền nguyên `msg` vừa đọc (cần `reactions` hiện tại để biết gỡ khoá nào).
-     * Gửi `ModifyMessagePropertyRequestBody` (lệnh 705) — xem README.
+     * Set YOUR reaction on a message — like TikTok Web, one reaction per user: a new `emoji` replaces the old one,
+     * `null` = remove. Pass the whole `msg` just read (current `reactions` are needed to know which key to remove).
+     * Sends `ModifyMessagePropertyRequestBody` (command 705) — see README.
      */
     async setReaction(msg, emoji) {
         const own = this.ctx.ownId;
@@ -173,7 +173,7 @@ class API {
             if (e === emoji)
                 continue;
             ops.push({ op: constants_1.PropertyOp.Remove, key: constants_1.REACTION_PREFIX + e });
-            // ❤️ thả từ app điện thoại còn nằm ở khoá cũ `e:love` — gỡ luôn kẻo app vẫn hiện tim.
+            // ❤️ sent from the mobile app still uses the legacy key `e:love` — remove it too or the app keeps showing the heart.
             if (e === constants_1.REACTION_HEART)
                 ops.push({ op: constants_1.PropertyOp.Remove, key: constants_1.REACTION_LOVE_KEY });
         }
@@ -188,12 +188,12 @@ class API {
         for (const o of ops)
             target.msg(6, new proto_1.Writer().int(1, o.op).bytes(2, o.key).bytes(4, own));
         const body = await this.ctx.im('/v1/message/set_property', constants_1.Cmd.SetMessageProperty, new proto_1.Writer().msg(1, target).bytes(2, 'deprecated').finish());
-        // status: 0 thành công, 1 gửi trùng (cũng là xong); còn lại TikTok từ chối.
+        // status: 0 success, 1 duplicate (also done); anything else means TikTok rejected it.
         const status = body.num(1);
         if (status > 1)
             throw new errors_1.TikTokError('IM_ERROR', `set_property: status ${status}`, status);
     }
-    /** Tải ảnh sticker (CDN công khai, không mã hoá, không cần cookie). */
+    /** Download a sticker image (public CDN, unencrypted, no cookie needed). */
     async downloadSticker(sticker) {
         const res = await fetch(sticker.url, {
             headers: { 'User-Agent': this.ctx.userAgent },
@@ -201,25 +201,25 @@ class API {
             signal: AbortSignal.timeout(this.ctx.options.timeoutMs ?? 20_000),
         }).catch(() => null);
         if (!res?.ok)
-            throw new errors_1.TikTokError('DOWNLOAD_FAILED', `Tải sticker lỗi: ${res?.status ?? 'mạng'}`);
+            throw new errors_1.TikTokError('DOWNLOAD_FAILED', `Sticker download failed: ${res?.status ?? 'network'}`);
         return { data: Buffer.from(await res.arrayBuffer()), type: res.headers.get('content-type') ?? 'image/webp' };
     }
-    /** Tải + giải mã ảnh của một tin (truyền cả `msg` — tin từ listener thiếu link, hàm tự tra lại). */
+    /** Download + decrypt a message's image (pass the whole `msg` — listener messages lack the URL, this looks it up). */
     async downloadImage(source, which = 'origin') {
         let image = 'serverMessageId' in source ? source.image : source;
-        // Tin đẩy qua websocket chỉ có uri + khoá, không có link tải → tra lại lịch sử theo mã tin.
+        // Websocket-pushed messages only have uri + key, no download URL → look up history by message id.
         if ('serverMessageId' in source && image && !image.url) {
             const { messages } = await this.getMessages(source, { limit: 5, before: (BigInt(source.index) + 1n).toString() });
             image = messages.find((m) => m.serverMessageId === source.serverMessageId)?.image ?? image;
         }
         if (!image)
-            throw new errors_1.TikTokError('DOWNLOAD_FAILED', 'Tin không có ảnh');
+            throw new errors_1.TikTokError('DOWNLOAD_FAILED', 'Message has no image');
         return this.media.download(image, which);
     }
-    /** `SendMessageRequestBody`: {1 convId, 2 loại hội thoại, 3 shortId, 4 nội dung, 5 ext, 6 loại tin, 7 ticket, 8 client id, …}. */
+    /** `SendMessageRequestBody`: {1 convId, 2 conversation type, 3 shortId, 4 content, 5 ext, 6 message type, 7 ticket, 8 client id, …}. */
     async send(conv, cid, type, content, extra) {
         if (!conv.conversationId || !conv.conversationShortId) {
-            throw new errors_1.TikTokError('IM_ERROR', 'Thiếu conversationId / conversationShortId');
+            throw new errors_1.TikTokError('IM_ERROR', 'Missing conversationId / conversationShortId');
         }
         const w = new proto_1.Writer()
             .bytes(1, conv.conversationId)
@@ -235,7 +235,7 @@ class API {
     }
 }
 exports.API = API;
-/** Tài khoản của cookie — `null` nếu cookie không còn đăng nhập. */
+/** Account for the cookie — `null` if the cookie is no longer logged in. */
 async function fetchAccount(ctx) {
     const res = await ctx.getJson(`${constants_1.WEB}/passport/web/account/info/?aid=${constants_1.AID_FRONTIER}`);
     if (res.message !== 'success' || !res.data?.user_id_str)
@@ -248,8 +248,8 @@ async function fetchAccount(ctx) {
     };
 }
 /**
- * Link ảnh đại diện trong `avatars` của hồ sơ IM — gom mọi chuỗi `https://…` (cỡ thumb → medium → larger, tuỳ
- * TikTok trả gì), rồi xếp bản trình duyệt đọc được (jpeg/webp/png) lên trước, heic xuống cuối.
+ * Avatar URLs from the IM profile `avatars` — collects every `https://…` string (thumb → medium → larger, whatever
+ * TikTok returns), then puts browser-readable ones (jpeg/webp/png) first and heic last.
  */
 function avatarLinks(avatars) {
     const urls = [];
@@ -268,7 +268,7 @@ function avatarLinks(avatars) {
     const ranked = [...urls.filter((u) => !heic(u)), ...urls.filter(heic)];
     return { avatar: ranked[0] ?? '', avatars: ranked };
 }
-/** `wid` — mã máy TikTok cấp theo cookie `ttwid`; IM + websocket dùng làm `device_id`. */
+/** `wid` — device id TikTok issues per `ttwid` cookie; IM + websocket use it as `device_id`. */
 async function fetchWebId(ctx) {
     const res = await ctx.fetch(`${constants_1.WEB}/api/v1/web-cookie-privacy/config?locale=vi-VN&appId=1988&theme=default&tea=1`);
     if (!res.ok)

package/dist/constants.d.ts

@@ -1,35 +1,35 @@
 /**
- * Hằng giao thức IM của TikTok Web — dựng lại từ lưu lượng `tiktok.com/business-suite/messages`
- * (09/11/2026). TikTok đổi phía họ thì sửa ở đây; ghi lại cách dò ra ở README.
+ * TikTok Web IM protocol constants — reconstructed from `tiktok.com/business-suite/messages` traffic
+ * (09/11/2026). If TikTok changes things on their side, fix them here; how they were found is in the README.
  */
 export declare const IM_API = "https://im-api-sg.tiktok.com";
 export declare const IM_WS = "wss://im-ws-sg.tiktok.com/ws/v2";
 export declare const WEB = "https://www.tiktok.com";
 export declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36";
-/** App id của TikTok Web (HTTP IM). */
+/** TikTok Web app id (HTTP IM). */
 export declare const AID_WEB = "1988";
-/** App id kênh "frontier" — websocket đẩy tin mới. */
+/** "frontier" channel app id — websocket pushing new messages. */
 export declare const AID_FRONTIER = "1459";
 export declare const SDK_VERSION = "1.8.5";
 export declare const BUILD_NUMBER = "feffaa1:master";
-/** `access_key` của websocket = md5(FPID + APP_KEY + device_id + SALT). */
+/** Websocket `access_key` = md5(FPID + APP_KEY + device_id + SALT). */
 export declare const FRONTIER_FPID = "9";
 export declare const FRONTIER_APP_KEY = "e1bd35ec9db7b8d846de66ed140b1ad9";
 export declare const FRONTIER_SALT = "f8a69f1719916z";
-/** Lệnh IM (`Request.cmd`) — đồng thời là số trường của body trong `RequestBody`. */
+/** IM command (`Request.cmd`) — also the body's field number in `RequestBody`. */
 export declare const Cmd: {
     readonly SendMessage: 100;
     readonly GetMessagesByUserInit: 203;
     readonly GetMessagesByConversation: 301;
-    /** Websocket đẩy tin mới. */
+    /** Websocket push of new messages. */
     readonly NewMessage: 500;
-    /** Thả / gỡ reaction (`property` của tin) — `/v1/message/set_property`. */
+    /** Add / remove a reaction (message `property`) — `/v1/message/set_property`. */
     readonly SetMessageProperty: 705;
     readonly GetConversationInfo: 610;
     readonly MarkRead: 2002;
     readonly UploadConfig: 2059;
 };
-/** Body của MarkRead nằm ở trường 604, không trùng số lệnh. */
+/** MarkRead's body lives in field 604, not the command number. */
 export declare const MARK_READ_BODY_FIELD = 604;
 /** `MessageBody.message_type`. */
 export declare const MessageType: {
@@ -37,15 +37,15 @@ export declare const MessageType: {
     readonly Text: 7;
     readonly ShareVideo: 8;
     readonly PrivateImage: 1802;
-    /** Sticker (nhãn dán) — ảnh công khai trên CDN sticker, không mã hoá. */
+    /** Sticker — public image on the sticker CDN, not encrypted. */
     readonly Sticker: 1805;
-    /** Lệnh ẩn (đã đọc…) — không hiện trong hội thoại, websocket vẫn đẩy. */
+    /** Hidden command (read receipt…) — not shown in the conversation, but still pushed over websocket. */
     readonly Command: 50001;
 };
 export declare const ConversationType: {
     readonly OneToOne: 1;
 };
-/** Trường của `Response` (cả HTTP lẫn payload websocket). */
+/** `Response` fields (both HTTP and websocket payload). */
 export declare const Resp: {
     readonly cmd: 1;
     readonly seq: 2;
@@ -54,7 +54,7 @@ export declare const Resp: {
     readonly body: 6;
     readonly logId: 7;
 };
-/** Trường của `MessageBody`. */
+/** `MessageBody` fields. */
 export declare const MsgF: {
     readonly conversationId: 1;
     readonly conversationType: 2;
@@ -66,21 +66,21 @@ export declare const MsgF: {
     readonly content: 8;
     readonly ext: 9;
     readonly createTime: 10;
-    /** `property_list` — reaction: `{1 khoá "e:<emoji>", 2 {1 PropertyItem[]}}`. */
+    /** `property_list` — reaction: `{1 key "e:<emoji>", 2 {1 PropertyItem[]}}`. */
     readonly propertyList: 15;
     readonly attachments: 20;
     readonly tag: 21;
 };
-/** Thao tác trên `property` của tin (`ModifyPropertyContent.operation`). */
+/** Operation on a message `property` (`ModifyPropertyContent.operation`). */
 export declare const PropertyOp: {
     readonly Add: 0;
     readonly Remove: 1;
 };
-/** Khoá reaction = `e:<emoji>`. App điện thoại thả ❤️ còn ghi thêm khoá cũ `e:love` — coi như ❤️. */
+/** Reaction key = `e:<emoji>`. The mobile app reacting ❤️ also writes the legacy key `e:love` — treated as ❤️. */
 export declare const REACTION_PREFIX = "e:";
 export declare const REACTION_LOVE_KEY = "e:love";
 export declare const REACTION_HEART = "\u2764\uFE0F";
-/** ImageX — nơi tải ảnh lên (ký kiểu AWS SigV4). */
+/** ImageX — image upload endpoint (AWS SigV4-style signing). */
 export declare const IMAGEX_REGION = "cn-north-1";
 export declare const IMAGEX_SERVICE = "imagex";
 export declare const IMAGEX_VERSION = "2018-08-01";

package/dist/constants.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
- * Hằng giao thức IM của TikTok Web — dựng lại từ lưu lượng `tiktok.com/business-suite/messages`
- * (09/11/2026). TikTok đổi phía họ thì sửa ở đây; ghi lại cách dò ra ở README.
+ * TikTok Web IM protocol constants — reconstructed from `tiktok.com/business-suite/messages` traffic
+ * (09/11/2026). If TikTok changes things on their side, fix them here; how they were found is in the README.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IMAGEX_VERSION = exports.IMAGEX_SERVICE = exports.IMAGEX_REGION = exports.REACTION_HEART = exports.REACTION_LOVE_KEY = exports.REACTION_PREFIX = exports.PropertyOp = exports.MsgF = exports.Resp = exports.ConversationType = exports.MessageType = exports.MARK_READ_BODY_FIELD = exports.Cmd = exports.FRONTIER_SALT = exports.FRONTIER_APP_KEY = exports.FRONTIER_FPID = exports.BUILD_NUMBER = exports.SDK_VERSION = exports.AID_FRONTIER = exports.AID_WEB = exports.DEFAULT_USER_AGENT = exports.WEB = exports.IM_WS = exports.IM_API = void 0;
@@ -9,30 +9,30 @@ exports.IM_API = 'https://im-api-sg.tiktok.com';
 exports.IM_WS = 'wss://im-ws-sg.tiktok.com/ws/v2';
 exports.WEB = 'https://www.tiktok.com';
 exports.DEFAULT_USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36';
-/** App id của TikTok Web (HTTP IM). */
+/** TikTok Web app id (HTTP IM). */
 exports.AID_WEB = '1988';
-/** App id kênh "frontier" — websocket đẩy tin mới. */
+/** "frontier" channel app id — websocket pushing new messages. */
 exports.AID_FRONTIER = '1459';
 exports.SDK_VERSION = '1.8.5';
 exports.BUILD_NUMBER = 'feffaa1:master';
-/** `access_key` của websocket = md5(FPID + APP_KEY + device_id + SALT). */
+/** Websocket `access_key` = md5(FPID + APP_KEY + device_id + SALT). */
 exports.FRONTIER_FPID = '9';
 exports.FRONTIER_APP_KEY = 'e1bd35ec9db7b8d846de66ed140b1ad9';
 exports.FRONTIER_SALT = 'f8a69f1719916z';
-/** Lệnh IM (`Request.cmd`) — đồng thời là số trường của body trong `RequestBody`. */
+/** IM command (`Request.cmd`) — also the body's field number in `RequestBody`. */
 exports.Cmd = {
     SendMessage: 100,
     GetMessagesByUserInit: 203,
     GetMessagesByConversation: 301,
-    /** Websocket đẩy tin mới. */
+    /** Websocket push of new messages. */
     NewMessage: 500,
-    /** Thả / gỡ reaction (`property` của tin) — `/v1/message/set_property`. */
+    /** Add / remove a reaction (message `property`) — `/v1/message/set_property`. */
     SetMessageProperty: 705,
     GetConversationInfo: 610,
     MarkRead: 2002,
     UploadConfig: 2059,
 };
-/** Body của MarkRead nằm ở trường 604, không trùng số lệnh. */
+/** MarkRead's body lives in field 604, not the command number. */
 exports.MARK_READ_BODY_FIELD = 604;
 /** `MessageBody.message_type`. */
 exports.MessageType = {
@@ -40,15 +40,15 @@ exports.MessageType = {
     Text: 7,
     ShareVideo: 8,
     PrivateImage: 1802,
-    /** Sticker (nhãn dán) — ảnh công khai trên CDN sticker, không mã hoá. */
+    /** Sticker — public image on the sticker CDN, not encrypted. */
     Sticker: 1805,
-    /** Lệnh ẩn (đã đọc…) — không hiện trong hội thoại, websocket vẫn đẩy. */
+    /** Hidden command (read receipt…) — not shown in the conversation, but still pushed over websocket. */
     Command: 50001,
 };
 exports.ConversationType = { OneToOne: 1 };
-/** Trường của `Response` (cả HTTP lẫn payload websocket). */
+/** `Response` fields (both HTTP and websocket payload). */
 exports.Resp = { cmd: 1, seq: 2, status: 3, error: 4, body: 6, logId: 7 };
-/** Trường của `MessageBody`. */
+/** `MessageBody` fields. */
 exports.MsgF = {
     conversationId: 1,
     conversationType: 2,
@@ -60,18 +60,18 @@ exports.MsgF = {
     content: 8,
     ext: 9,
     createTime: 10,
-    /** `property_list` — reaction: `{1 khoá "e:<emoji>", 2 {1 PropertyItem[]}}`. */
+    /** `property_list` — reaction: `{1 key "e:<emoji>", 2 {1 PropertyItem[]}}`. */
     propertyList: 15,
     attachments: 20,
     tag: 21,
 };
-/** Thao tác trên `property` của tin (`ModifyPropertyContent.operation`). */
+/** Operation on a message `property` (`ModifyPropertyContent.operation`). */
 exports.PropertyOp = { Add: 0, Remove: 1 };
-/** Khoá reaction = `e:<emoji>`. App điện thoại thả ❤️ còn ghi thêm khoá cũ `e:love` — coi như ❤️. */
+/** Reaction key = `e:<emoji>`. The mobile app reacting ❤️ also writes the legacy key `e:love` — treated as ❤️. */
 exports.REACTION_PREFIX = 'e:';
 exports.REACTION_LOVE_KEY = 'e:love';
 exports.REACTION_HEART = '\u2764\uFE0F';
-/** ImageX — nơi tải ảnh lên (ký kiểu AWS SigV4). */
+/** ImageX — image upload endpoint (AWS SigV4-style signing). */
 exports.IMAGEX_REGION = 'cn-north-1';
 exports.IMAGEX_SERVICE = 'imagex';
 exports.IMAGEX_VERSION = '2018-08-01';

package/dist/context.d.ts

@@ -1,14 +1,14 @@
 import { Msg } from './proto';
 import type { Credentials, TikTokOptions } from './types';
-/** Cookie dạng `name → value` từ mọi kiểu đầu vào của `Credentials.cookies`. */
+/** `name → value` cookies from any input shape of `Credentials.cookies`. */
 export declare function normalizeCookies(input: Credentials['cookies']): Map<string, string>;
-/** Trạng thái dùng chung của một phiên: cookie, mã máy, uid, gọi HTTP. */
+/** Shared state of a session: cookies, device id, uid, HTTP calls. */
 export declare class Context {
     readonly options: TikTokOptions;
     readonly cookies: Map<string, string>;
     /**
-     * Mã máy IM = `wid` TikTok cấp theo cookie `ttwid` (`login` tự hỏi). Websocket chỉ nhận đúng
-     * mã này — mã tự bịa bị 400 (HTTP IM thì không kén).
+     * IM device id = the `wid` TikTok issues for the `ttwid` cookie (`login` fetches it). The websocket only
+     * accepts this id — a made-up id gets 400 (HTTP IM isn't picky).
      */
     deviceId: string;
     readonly userAgent: string;
@@ -17,16 +17,16 @@ export declare class Context {
     constructor(creds: Credentials, options?: TikTokOptions);
     cookieHeader(): string;
     log(level: 'debug' | 'warn', msg: string): void;
-    /** `fetch` kèm cookie + UA + hạn chờ. */
+    /** `fetch` with cookies + UA + timeout. */
     fetch(url: string, init?: RequestInit & {
         headers?: Record<string, string>;
     }): Promise<Response>;
     getJson<T>(url: string): Promise<T>;
-    /** Vỏ `Request` của IM: lệnh + body + đầu mục chung. */
+    /** IM `Request` envelope: command + body + common headers. */
     buildRequest(cmd: number, bodyField: number, body: Buffer): Buffer;
     /**
-     * Gọi một lệnh IM qua HTTP. Trả body đã bóc (`ResponseBody[cmd]`).
-     * KHÔNG cần chữ ký X-Gnarly/X-Bogus/msToken — server IM chỉ xét cookie (thử 09/11/2026).
+     * Call an IM command over HTTP. Returns the unwrapped body (`ResponseBody[cmd]`).
+     * NO X-Gnarly/X-Bogus/msToken signature needed — the IM server only checks cookies (tested 09/11/2026).
      */
     im(path: string, cmd: number, body: Buffer, bodyField?: number): Promise<Msg>;
 }

package/dist/context.js

@@ -5,7 +5,7 @@ exports.normalizeCookies = normalizeCookies;
 const constants_1 = require("./constants");
 const errors_1 = require("./errors");
 const proto_1 = require("./proto");
-/** Cookie dạng `name → value` từ mọi kiểu đầu vào của `Credentials.cookies`. */
+/** `name → value` cookies from any input shape of `Credentials.cookies`. */
 function normalizeCookies(input) {
     const jar = new Map();
     if (typeof input === 'string') {
@@ -26,13 +26,13 @@ function normalizeCookies(input) {
     }
     return jar;
 }
-/** Trạng thái dùng chung của một phiên: cookie, mã máy, uid, gọi HTTP. */
+/** Shared state of a session: cookies, device id, uid, HTTP calls. */
 class Context {
     options;
     cookies;
     /**
-     * Mã máy IM = `wid` TikTok cấp theo cookie `ttwid` (`login` tự hỏi). Websocket chỉ nhận đúng
-     * mã này — mã tự bịa bị 400 (HTTP IM thì không kén).
+     * IM device id = the `wid` TikTok issues for the `ttwid` cookie (`login` fetches it). The websocket only
+     * accepts this id — a made-up id gets 400 (HTTP IM isn't picky).
      */
     deviceId;
     userAgent;
@@ -50,7 +50,7 @@ class Context {
     log(level, msg) {
         this.options.logger?.(level, msg);
     }
-    /** `fetch` kèm cookie + UA + hạn chờ. */
+    /** `fetch` with cookies + UA + timeout. */
     async fetch(url, init = {}) {
         try {
             return await fetch(url, {
@@ -75,7 +75,7 @@ class Context {
             throw new errors_1.TikTokError('HTTP_ERROR', `${url.split('?')[0]}: HTTP ${res.status}`, res.status);
         return (await res.json());
     }
-    /** Vỏ `Request` của IM: lệnh + body + đầu mục chung. */
+    /** IM `Request` envelope: command + body + common headers. */
     buildRequest(cmd, bodyField, body) {
         return new proto_1.Writer()
             .int(1, cmd)
@@ -101,8 +101,8 @@ class Context {
             .finish();
     }
     /**
-     * Gọi một lệnh IM qua HTTP. Trả body đã bóc (`ResponseBody[cmd]`).
-     * KHÔNG cần chữ ký X-Gnarly/X-Bogus/msToken — server IM chỉ xét cookie (thử 09/11/2026).
+     * Call an IM command over HTTP. Returns the unwrapped body (`ResponseBody[cmd]`).
+     * NO X-Gnarly/X-Bogus/msToken signature needed — the IM server only checks cookies (tested 09/11/2026).
      */
     async im(path, cmd, body, bodyField = cmd) {
         const url = `${constants_1.IM_API}${path}?aid=${constants_1.AID_WEB}&version_code=1.0.0&app_name=tiktok_web&device_platform=web_pc`;
@@ -115,11 +115,11 @@ class Context {
             throw new errors_1.TikTokError('HTTP_ERROR', `${path}: HTTP ${res.status}`, res.status);
         const resp = proto_1.Msg.tryParse(Buffer.from(await res.arrayBuffer()));
         if (!resp)
-            throw new errors_1.TikTokError('BAD_RESPONSE', `${path}: phản hồi không phải protobuf`);
+            throw new errors_1.TikTokError('BAD_RESPONSE', `${path}: response is not protobuf`);
         const status = resp.num(constants_1.Resp.status);
         if (status !== 0) {
             const desc = resp.str(constants_1.Resp.error);
-            // Chưa đăng nhập: 200005 (thử bằng request không cookie).
+            // Not logged in: 200005 (tested with a cookieless request).
             const code = status === 200005 ? 'SESSION_EXPIRED' : 'IM_ERROR';
             throw new errors_1.TikTokError(code, `${path}: ${status} ${desc}`.trim(), status);
         }

package/dist/errors.d.ts

@@ -1,18 +1,18 @@
-/** Lỗi từ TikTok hoặc từ chính thư viện. `code` để bên dùng phân nhánh (vd phiên hết hạn → quét lại). */
+/** Error from TikTok or from the library itself. `code` lets callers branch (e.g. session expired → rescan). */
 export declare class TikTokError extends Error {
     readonly code: TikTokErrorCode;
-    /** Mã gốc TikTok trả (status_code / error_code) nếu có. */
+    /** Original TikTok code (status_code / error_code), if any. */
     readonly upstream?: number | string | undefined;
     constructor(code: TikTokErrorCode, message: string, 
-    /** Mã gốc TikTok trả (status_code / error_code) nếu có. */
+    /** Original TikTok code (status_code / error_code), if any. */
     upstream?: number | string | undefined);
 }
 export type TikTokErrorCode = 
-/** Cookie không còn đăng nhập — phải lấy phiên mới. */
+/** Cookie is no longer logged in — a new session is required. */
 'SESSION_EXPIRED' | 'HTTP_ERROR'
-/** IM trả `status_code` khác 0. */
+/** IM returned a non-zero `status_code`. */
  | 'IM_ERROR' | 'UPLOAD_FAILED' | 'DOWNLOAD_FAILED' | 'BAD_RESPONSE'
-/** Đăng nhập QR không thành (Chrome không mở được, QR hết hạn, không thấy cookie…). */
+/** QR login failed (Chrome failed to launch, QR expired, no cookie found…). */
  | 'LOGIN_FAILED'
-/** Bên gọi huỷ đăng nhập QR (`signal`). */
+/** Caller aborted QR login (`signal`). */
  | 'LOGIN_ABORTED';

package/dist/errors.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TikTokError = void 0;
-/** Lỗi từ TikTok hoặc từ chính thư viện. `code` để bên dùng phân nhánh (vd phiên hết hạn → quét lại). */
+/** Error from TikTok or from the library itself. `code` lets callers branch (e.g. session expired → rescan). */
 class TikTokError extends Error {
     code;
     upstream;
     constructor(code, message, 
-    /** Mã gốc TikTok trả (status_code / error_code) nếu có. */
+    /** Original TikTok code (status_code / error_code), if any. */
     upstream) {
         super(message);
         this.code = code;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * tca — TikTok Chat API (giả lập TikTok Web), cùng ý tưởng với zca-js cho Zalo.
+ * tca-js — unofficial TikTok Chat API (speaks the TikTok Web protocol).
  *
  * ```ts
  * const api = await new TikTok().login({ cookies, deviceId });
@@ -10,15 +10,15 @@
  * api.listener.start();
  * ```
  *
- * Lấy cookie lần đầu: `loginQR({ chromePath, onEvent })` — mở Chrome headless ở trang QR của TikTok
- * (API đăng nhập đòi chữ ký JS nên không làm thuần Node được), quét xong trả cookie. Xem README.
+ * Getting cookies the first time: `loginQR({ chromePath, onEvent })` — opens headless Chrome on TikTok's QR page
+ * (the login API requires a JS signature so it can't be done in pure Node), returns cookies after scanning. See README.
  */
 import { API } from './api';
 import type { Credentials, TikTokOptions } from './types';
 export declare class TikTok {
     private readonly options;
     constructor(options?: TikTokOptions);
-    /** Đăng nhập bằng cookie đã có. Cookie hết hạn → `TikTokError('SESSION_EXPIRED')`. */
+    /** Log in with existing cookies. Expired cookies → `TikTokError('SESSION_EXPIRED')`. */
     login(credentials: Credentials): Promise<API>;
 }
 export { API } from './api';