tca-js 0.3.0 → 0.3.1

package/dist/index.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loginQR = exports.MANUAL_CLOSE = exports.Listener = exports.TikTokError = exports.MessageType = exports.API = exports.TikTok = void 0;
 /**
- * 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 });
@@ -13,8 +13,8 @@ exports.loginQR = exports.MANUAL_CLOSE = exports.Listener = exports.TikTokError
  * 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.
  */
 const api_1 = require("./api");
 const context_1 = require("./context");
@@ -24,19 +24,19 @@ class TikTok {
     constructor(options = {}) {
         this.options = options;
     }
-    /** Đă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')`. */
     async login(credentials) {
         const ctx = new context_1.Context(credentials, this.options);
         if (!ctx.cookies.get('sessionid') && !ctx.cookies.get('sid_tt')) {
-            throw new errors_1.TikTokError('SESSION_EXPIRED', 'Cookie không có sessionid');
+            throw new errors_1.TikTokError('SESSION_EXPIRED', 'Cookie has no sessionid');
         }
         const account = await (0, api_1.fetchAccount)(ctx);
         if (!account)
-            throw new errors_1.TikTokError('SESSION_EXPIRED', 'Cookie TikTok không còn đăng nhập');
+            throw new errors_1.TikTokError('SESSION_EXPIRED', 'TikTok cookie is no longer logged in');
         ctx.ownId = account.uid;
         ctx.deviceId = (await (0, api_1.fetchWebId)(ctx).catch(() => '')) || ctx.deviceId;
         if (!ctx.deviceId)
-            throw new errors_1.TikTokError('BAD_RESPONSE', 'Không lấy được wid (device_id) — cookie thiếu ttwid?');
+            throw new errors_1.TikTokError('BAD_RESPONSE', 'Could not get wid (device_id) — cookie missing ttwid?');
         return new api_1.API(ctx, account);
     }
 }

package/dist/listener.d.ts

@@ -1,21 +1,21 @@
 import { EventEmitter } from 'node:events';
 import type { Context } from './context';
 import type { TikTokMessage } from './types';
-/** Mã đóng do chính mình gọi `stop()`. */
+/** Close code used when we call `stop()` ourselves. */
 export declare const MANUAL_CLOSE = 4000;
 export interface ListenerEvents {
     connected: [];
-    /** Tin thật trong hội thoại (cả tin của chính mình — xem `isSelf`). */
+    /** A real message in a conversation (including our own — see `isSelf`). */
     message: [TikTokMessage];
-    /** Lệnh ẩn: đánh dấu đã đọc… (`content.command_type`). */
+    /** Hidden command: mark as read… (`content.command_type`). */
     command: [TikTokMessage];
-    /** Mã + lý do đóng. Không phải `MANUAL_CLOSE` thì listener tự nối lại (nếu bật). */
+    /** Close code + reason. Unless `MANUAL_CLOSE`, the listener reconnects automatically (if enabled). */
     closed: [number, string];
     error: [Error];
 }
 /**
- * Nghe tin mới qua websocket `im-ws-sg` (aid 1459) — chỉ cần cookie, như listener của zca-js.
- * Sự kiện: `connected`, `message`, `closed`, `error`.
+ * Listen for new messages via the `im-ws-sg` websocket (aid 1459) — cookies only.
+ * Events: `connected`, `message`, `closed`, `error`.
  */
 export declare class Listener extends EventEmitter<ListenerEvents> {
     private readonly ctx;
@@ -29,7 +29,7 @@ export declare class Listener extends EventEmitter<ListenerEvents> {
     constructor(ctx: Context);
     get connected(): boolean;
     url(): string;
-    /** Mở kết nối. `retryOnClose` (mặc định bật): rớt mạng thì tự nối lại, giãn dần tới 1 phút. */
+    /** Open the connection. `retryOnClose` (on by default): reconnect on drop, backing off up to 1 minute. */
     start(opts?: {
         retryOnClose?: boolean;
     }): void;
@@ -38,6 +38,6 @@ export declare class Listener extends EventEmitter<ListenerEvents> {
     private touch;
     private clearTimers;
     private onFrame;
-    /** Báo đã nhận — `ack_id = <giờ base36>:<x_frontier_traceid>`, kèm lại seq/logid của khung. */
+    /** Acknowledge receipt — `ack_id = <base36 time>:<x_frontier_traceid>`, echoing the frame's seq/logid. */
     private ack;
 }

package/dist/listener.js

@@ -11,19 +11,19 @@ const constants_1 = require("./constants");
 const lz4_1 = require("./lz4");
 const message_1 = require("./message");
 const proto_1 = require("./proto");
-/** Trình duyệt gửi "hi" mỗi 15–30 giây; lấy cận dưới. */
+/** The browser sends "hi" every 15–30 seconds; use the lower bound. */
 const HEARTBEAT_MS = 15_000;
-/** Không nhận gì (kể cả "hi" đáp lại) quá chừng này thì coi như chết ngầm, nối lại. */
+/** If nothing (not even a "hi" reply) arrives for this long, treat it as silently dead and reconnect. */
 const IDLE_TIMEOUT_MS = 75_000;
 const RECONNECT_MIN_MS = 2_000;
 const RECONNECT_MAX_MS = 60_000;
-/** Server đẩy cùng một tin vài lần (mỗi thiết bị một khung) — nhớ chừng này mã tin để lọc trùng. */
+/** The server pushes the same message several times (one frame per device) — remember this many message IDs to dedupe. */
 const DEDUPE_KEEP = 500;
-/** Mã đóng do chính mình gọi `stop()`. */
+/** Close code used when we call `stop()` ourselves. */
 exports.MANUAL_CLOSE = 4000;
 /**
- * Nghe tin mới qua websocket `im-ws-sg` (aid 1459) — chỉ cần cookie, như listener của zca-js.
- * Sự kiện: `connected`, `message`, `closed`, `error`.
+ * Listen for new messages via the `im-ws-sg` websocket (aid 1459) — cookies only.
+ * Events: `connected`, `message`, `closed`, `error`.
  */
 class Listener extends node_events_1.EventEmitter {
     ctx;
@@ -52,7 +52,7 @@ class Listener extends node_events_1.EventEmitter {
             version_code: 'fws_1.0.0',
             access_key: accessKey,
             device_id: this.ctx.deviceId,
-            // Giá trị cookie đã URL-encode sẵn (`1%7C…`) — giải ra để URLSearchParams không mã hoá hai lần.
+            // Cookie value is already URL-encoded (`1%7C…`) — decode it so URLSearchParams doesn't double-encode.
             ttwid: decodeURIComponent(this.ctx.cookies.get('ttwid') ?? ''),
             xsack: '1',
             xaack: '1',
@@ -60,7 +60,7 @@ class Listener extends node_events_1.EventEmitter {
         });
         return `${constants_1.IM_WS}?${q}`;
     }
-    /** Mở kết nối. `retryOnClose` (mặc định bật): rớt mạng thì tự nối lại, giãn dần tới 1 phút. */
+    /** Open the connection. `retryOnClose` (on by default): reconnect on drop, backing off up to 1 minute. */
     start(opts = {}) {
         this.retry = opts.retryOnClose ?? true;
         this.connect();
@@ -86,13 +86,13 @@ class Listener extends node_events_1.EventEmitter {
             this.backoff = RECONNECT_MIN_MS;
             this.heartbeat = setInterval(() => ws.readyState === ws_1.default.OPEN && ws.send('hi'), HEARTBEAT_MS);
             this.touch();
-            this.ctx.log('debug', 'tca: websocket đã nối');
+            this.ctx.log('debug', 'tca: websocket connected');
             this.emit('connected');
         });
         ws.on('message', (data, isBinary) => {
             this.touch();
             if (!isBinary)
-                return; // "hi" đáp lại
+                return; // "hi" reply
             try {
                 this.onFrame(ws, data);
             }
@@ -103,7 +103,7 @@ class Listener extends node_events_1.EventEmitter {
         ws.on('error', (err) => this.emit('error', err));
         ws.on('close', (code, reason) => {
             if (this.ws !== ws)
-                return; // kết nối cũ đã bị thay
+                return; // old connection was replaced
             this.ws = null;
             this.clearTimers();
             this.emit('closed', code, reason.toString());
@@ -111,7 +111,7 @@ class Listener extends node_events_1.EventEmitter {
                 return;
             const wait = this.backoff;
             this.backoff = Math.min(this.backoff * 2, RECONNECT_MAX_MS);
-            this.ctx.log('warn', `tca: websocket đóng (${code}) — nối lại sau ${wait / 1000}s`);
+            this.ctx.log('warn', `tca: websocket closed (${code}) — reconnecting in ${wait / 1000}s`);
             this.reconnectTimer = setTimeout(() => this.connect(), wait);
         });
     }
@@ -119,7 +119,7 @@ class Listener extends node_events_1.EventEmitter {
         if (this.idle)
             clearTimeout(this.idle);
         this.idle = setTimeout(() => {
-            this.ctx.log('warn', 'tca: websocket im lặng quá lâu — nối lại');
+            this.ctx.log('warn', 'tca: websocket silent too long — reconnecting');
             this.ws?.terminate();
         }, IDLE_TIMEOUT_MS);
     }
@@ -148,7 +148,7 @@ class Listener extends node_events_1.EventEmitter {
         const resp = proto_1.Msg.tryParse(payload);
         if (!resp || resp.num(constants_1.Resp.cmd) !== constants_1.Cmd.NewMessage)
             return;
-        // NewMessageNotify: {2 conversationId, 3 loại, 4 ?, 5 MessageBody}
+        // NewMessageNotify: {2 conversationId, 3 type, 4 ?, 5 MessageBody}
         const body = resp.msg(constants_1.Resp.body)?.msg(constants_1.Cmd.NewMessage)?.msg(5);
         if (!body)
             return;
@@ -163,7 +163,7 @@ class Listener extends node_events_1.EventEmitter {
         else
             this.emit('message', msg);
     }
-    /** Báo đã nhận — `ack_id = <giờ base36>:<x_frontier_traceid>`, kèm lại seq/logid của khung. */
+    /** Acknowledge receipt — `ack_id = <base36 time>:<x_frontier_traceid>`, echoing the frame's seq/logid. */
     ack(ws, f) {
         const ackId = `${Date.now().toString(36)}:${f.headers.x_frontier_traceid ?? ''}`;
         const out = new proto_1.Writer()

package/dist/lz4.d.ts

@@ -1,5 +1,5 @@
 /**
- * Giải nén LZ4 dạng block (không có frame header) — khung websocket có
- * `payload_encoding = "__lz4"` nén payload kiểu này. Không kéo thêm thư viện cho ~30 dòng.
+ * LZ4 block decompression (no frame header) — websocket frames with
+ * `payload_encoding = "__lz4"` compress their payload this way. No extra dependency for ~30 lines.
  */
 export declare function lz4Decompress(src: Buffer): Buffer;

package/dist/lz4.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.lz4Decompress = lz4Decompress;
 /**
- * Giải nén LZ4 dạng block (không có frame header) — khung websocket có
- * `payload_encoding = "__lz4"` nén payload kiểu này. Không kéo thêm thư viện cho ~30 dòng.
+ * LZ4 block decompression (no frame header) — websocket frames with
+ * `payload_encoding = "__lz4"` compress their payload this way. No extra dependency for ~30 lines.
  */
 function lz4Decompress(src) {
     let out = Buffer.alloc(Math.max(src.length * 4, 1024));
@@ -38,7 +38,7 @@ function lz4Decompress(src) {
         const offset = src[i] | (src[i + 1] << 8);
         i += 2;
         if (offset === 0 || offset > o)
-            throw new Error('lz4: offset hỏng');
+            throw new Error('lz4: invalid offset');
         let len = token & 15;
         if (len === 15) {
             let b;
@@ -49,7 +49,7 @@ function lz4Decompress(src) {
         }
         len += 4;
         ensure(len);
-        // Sao từng byte: vùng nguồn và đích được phép chồng nhau.
+        // Copy byte by byte: source and destination ranges may overlap.
         for (let k = 0; k < len; k++, o++)
             out[o] = out[o - offset];
     }

package/dist/media.d.ts

@@ -1,6 +1,6 @@
 import type { Context } from './context';
 import type { ImageInput, TikTokImage } from './types';
-/** Ảnh đã tải lên + được kho mã hoá — đủ để gửi tin ảnh. */
+/** Uploaded image, encrypted by the store — enough to send an image message. */
 export interface UploadedImage {
     uri: string;
     secretKey: string;
@@ -13,15 +13,15 @@ export declare class MediaClient {
     private readonly ctx;
     private cred;
     constructor(ctx: Context);
-    /** `UploadConfig` trả hai bộ khoá: loại 1 = ImageX (ảnh), loại 2 = VOD (video). Lấy loại 1. */
+    /** `UploadConfig` returns two credential sets: type 1 = ImageX (images), type 2 = VOD (video). Use type 1. */
     private credential;
-    /** Gọi ImageX ký AWS SigV4 (vùng cn-north-1, dịch vụ imagex). */
+    /** Call ImageX signed with AWS SigV4 (region cn-north-1, service imagex). */
     private imagex;
     /**
-     * Tải ảnh lên kho riêng tư của tin nhắn: Apply → POST file → Commit (kho tự mã hoá AES-GCM
-     * và trả khoá). Kích thước ảnh lấy từ kết quả Commit — không cần tự đọc ảnh.
+     * Upload an image to the private message store: Apply → POST file → Commit (the store encrypts with AES-GCM
+     * and returns the key). Image dimensions come from the Commit result — no need to decode the image.
      */
     upload(image: ImageInput): Promise<UploadedImage>;
-    /** Tải ảnh trong tin nhắn về và giải mã. Bố cục: IV 12 byte ‖ bản mã ‖ tag 16 byte. */
+    /** Download and decrypt a message image. Layout: 12-byte IV ‖ ciphertext ‖ 16-byte tag. */
     download(image: TikTokImage, which?: 'origin' | 'thumb'): Promise<Buffer>;
 }

package/dist/media.js

@@ -14,14 +14,14 @@ class MediaClient {
     constructor(ctx) {
         this.ctx = ctx;
     }
-    /** `UploadConfig` trả hai bộ khoá: loại 1 = ImageX (ảnh), loại 2 = VOD (video). Lấy loại 1. */
+    /** `UploadConfig` returns two credential sets: type 1 = ImageX (images), type 2 = VOD (video). Use type 1. */
     async credential() {
         if (this.cred && this.cred.expiresAt - Date.now() > 60_000)
             return this.cred;
         const body = await this.ctx.im('/v1/media/upload_config', constants_1.Cmd.UploadConfig, Buffer.alloc(0));
         const c = body.msgs(1).find((m) => m.num(1) === 1);
         if (!c)
-            throw new errors_1.TikTokError('UPLOAD_FAILED', 'upload_config không có khoá ImageX');
+            throw new errors_1.TikTokError('UPLOAD_FAILED', 'upload_config has no ImageX credentials');
         this.cred = {
             serviceId: c.str(2),
             host: c.str(3),
@@ -32,7 +32,7 @@ class MediaClient {
         };
         return this.cred;
     }
-    /** Gọi ImageX ký AWS SigV4 (vùng cn-north-1, dịch vụ imagex). */
+    /** Call ImageX signed with AWS SigV4 (region cn-north-1, service imagex). */
     async imagex(method, params, body) {
         const c = await this.credential();
         const amzDate = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+/, '');
@@ -78,8 +78,8 @@ class MediaClient {
         return json;
     }
     /**
-     * Tải ảnh lên kho riêng tư của tin nhắn: Apply → POST file → Commit (kho tự mã hoá AES-GCM
-     * và trả khoá). Kích thước ảnh lấy từ kết quả Commit — không cần tự đọc ảnh.
+     * Upload an image to the private message store: Apply → POST file → Commit (the store encrypts with AES-GCM
+     * and returns the key). Image dimensions come from the Commit result — no need to decode the image.
      */
     async upload(image) {
         const c = await this.credential();
@@ -96,13 +96,13 @@ class MediaClient {
         const store = addr.StoreInfos[0];
         const host = addr.UploadHosts[0];
         if (!store || !host)
-            throw new errors_1.TikTokError('UPLOAD_FAILED', 'ApplyImageUpload không trả chỗ tải lên');
+            throw new errors_1.TikTokError('UPLOAD_FAILED', 'ApplyImageUpload returned no upload target');
         const up = await fetch(`https://${host}/upload/v1/${store.StoreUri}`, {
             method: 'POST',
             headers: {
                 Authorization: store.Auth,
                 'Content-CRC32': ((0, node_zlib_1.crc32)(image.data) >>> 0).toString(16).padStart(8, '0'),
-                // Thiếu header này kho trả 4004 Not Found.
+                // Without this header the store returns 4004 Not Found.
                 'X-Storage-U': this.ctx.ownId,
                 'Content-Type': 'application/octet-stream',
                 'Content-Disposition': 'attachment; filename="undefined"',
@@ -118,7 +118,7 @@ class MediaClient {
         const enc = commit.Result.Results?.[0]?.Encryption;
         const plugin = commit.Result.PluginResult?.[0];
         if (!enc?.Uri || !enc.SecretKey)
-            throw new errors_1.TikTokError('UPLOAD_FAILED', 'CommitImageUpload không trả bản mã hoá');
+            throw new errors_1.TikTokError('UPLOAD_FAILED', 'CommitImageUpload returned no encrypted result');
         return {
             uri: enc.Uri,
             secretKey: enc.SecretKey,
@@ -128,14 +128,14 @@ class MediaClient {
             filename: image.filename,
         };
     }
-    /** Tải ảnh trong tin nhắn về và giải mã. Bố cục: IV 12 byte ‖ bản mã ‖ tag 16 byte. */
+    /** Download and decrypt a message image. Layout: 12-byte IV ‖ ciphertext ‖ 16-byte tag. */
     async download(image, which = 'origin') {
         const url = which === 'thumb' && image.thumbUrl ? image.thumbUrl : image.url;
         if (!url)
-            throw new errors_1.TikTokError('DOWNLOAD_FAILED', 'Ảnh không có link');
+            throw new errors_1.TikTokError('DOWNLOAD_FAILED', 'Image has no URL');
         const res = await this.ctx.fetch(url);
         if (!res.ok)
-            throw new errors_1.TikTokError('DOWNLOAD_FAILED', `Tải ảnh: HTTP ${res.status}`, res.status);
+            throw new errors_1.TikTokError('DOWNLOAD_FAILED', `Image download: HTTP ${res.status}`, res.status);
         const enc = Buffer.from(await res.arrayBuffer());
         if (!image.decryptKey)
             return enc;
@@ -145,7 +145,7 @@ class MediaClient {
             return Buffer.concat([d.update(enc.subarray(12, enc.length - 16)), d.final()]);
         }
         catch (err) {
-            throw new errors_1.TikTokError('DOWNLOAD_FAILED', `Giải mã ảnh: ${err instanceof Error ? err.message : String(err)}`);
+            throw new errors_1.TikTokError('DOWNLOAD_FAILED', `Image decryption: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }

package/dist/message.d.ts

@@ -2,5 +2,5 @@ import { Msg } from './proto';
 import type { TikTokConversation, TikTokMessage } from './types';
 /** `MessageBody` → `TikTokMessage`. */
 export declare function parseMessage(m: Msg, ownId: string): TikTokMessage;
-/** `ConversationInfo` (trường 2 của get_by_user_init): {1 id, 2 shortId, 3 loại, 6 {1 {1 uid}}…}. */
+/** `ConversationInfo` (field 2 of get_by_user_init): {1 id, 2 shortId, 3 type, 6 {1 {1 uid}}…}. */
 export declare function parseConversation(m: Msg, ownId: string): TikTokConversation;

package/dist/message.js

@@ -11,7 +11,7 @@ function parseJson(s) {
         return s;
     }
 }
-/** Ảnh trong `attachments` (trường 20 → 4): 1 = bản gốc, 2 = ảnh nhỏ; mỗi cái {1 uri, 2 url…, 5 {w,h}, 6 khoá}. */
+/** Image in `attachments` (field 20 → 4): 1 = original, 2 = thumbnail; each {1 uri, 2 url…, 5 {w,h}, 6 key}. */
 function parseImage(m) {
     const media = m.msg(constants_1.MsgF.attachments)?.msg(4);
     const origin = media?.msg(1);
@@ -28,8 +28,8 @@ function parseImage(m) {
     };
 }
 /**
- * Sticker (trường 20 → 7): `{1 {1 uri, 2 url, 5 {w,h}}, 2 lời nhắc, 200 {1 {2 map a:sticker_id, a:sticker_type…}}}`.
- * Link trỏ CDN sticker công khai (`…-dm-sticker-sign-…`) — không mã hoá, không cần cookie.
+ * Sticker (field 20 → 7): `{1 {1 uri, 2 url, 5 {w,h}}, 2 hint, 200 {1 {2 map a:sticker_id, a:sticker_type…}}}`.
+ * Links point to the public sticker CDN (`…-dm-sticker-sign-…`) — not encrypted, no cookies needed.
  */
 function parseSticker(m) {
     const st = m.msg(constants_1.MsgF.attachments)?.msg(7);
@@ -47,8 +47,8 @@ function parseSticker(m) {
     };
 }
 /**
- * Reaction (trường 15, `property_list`): mỗi phần tử `{1 khoá, 2 {1 PropertyItem[]}}`, khoá `e:<emoji>`,
- * `PropertyItem {1 uid, 3 giây, 4 idempotent_id, 6 µs}`. App điện thoại thả ❤️ ghi cả `e:❤️` lẫn `e:love` → gộp.
+ * Reaction (field 15, `property_list`): each entry `{1 key, 2 {1 PropertyItem[]}}`, key `e:<emoji>`,
+ * `PropertyItem {1 uid, 3 sec, 4 idempotent_id, 6 µs}`. The mobile app writes ❤️ as both `e:❤️` and `e:love` → merged.
  */
 function parseReactions(m) {
     const byEmoji = new Map();
@@ -101,7 +101,7 @@ function parseMessage(m, ownId) {
         ext,
     };
 }
-/** `ConversationInfo` (trường 2 của get_by_user_init): {1 id, 2 shortId, 3 loại, 6 {1 {1 uid}}…}. */
+/** `ConversationInfo` (field 2 of get_by_user_init): {1 id, 2 shortId, 3 type, 6 {1 {1 uid}}…}. */
 function parseConversation(m, ownId) {
     const participants = (m.msg(6)?.msgs(1) ?? []).map((p) => p.id(1));
     return {

package/dist/proto.d.ts

@@ -1,8 +1,8 @@
 /**
- * Protobuf tối thiểu, không cần file `.proto`.
+ * Minimal protobuf, no `.proto` file needed.
  *
- * TikTok không công bố `.proto` của IM — số trường ở `constants.ts` dựng lại từ byte bắt được
- * trên trình duyệt (09/11/2026). Chỉ cần ba kiểu dây: varint (0), độ dài (2), và bỏ qua 1/5.
+ * TikTok doesn't publish its IM `.proto` — field numbers in `constants.ts` were reconstructed from bytes captured
+ * in the browser (09/11/2026). Only three wire types are needed: varint (0), length-delimited (2), and skipping 1/5.
  */
 export interface Field {
     n: number;
@@ -10,9 +10,9 @@ export interface Field {
     int: bigint;
     bytes: Buffer;
 }
-/** Tách một message thành danh sách trường. `null` nếu byte không phải protobuf hợp lệ. */
+/** Split a message into a list of fields. `null` if the bytes are not valid protobuf. */
 export declare function decodeFields(b: Buffer): Field[] | null;
-/** Message đã giải — đọc theo số trường. */
+/** Decoded message — read by field number. */
 export declare class Msg {
     readonly fields: Field[];
     private constructor();
@@ -21,23 +21,23 @@ export declare class Msg {
     has(n: number): boolean;
     int(n: number): bigint;
     num(n: number): number;
-    /** Số nguyên 64-bit dạng chuỗi — uid / mã tin vượt `Number.MAX_SAFE_INTEGER`. */
+    /** 64-bit integer as a string — uids / message IDs exceed `Number.MAX_SAFE_INTEGER`. */
     id(n: number): string;
     bytes(n: number): Buffer;
     str(n: number): string;
     strs(n: number): string[];
     msg(n: number): Msg | null;
     msgs(n: number): Msg[];
-    /** `map<string,string>` — mỗi phần tử là message `{1: key, 2: value}`. */
+    /** `map<string,string>` — each entry is a message `{1: key, 2: value}`. */
     map(n: number): Record<string, string>;
 }
-/** Ghép message theo thứ tự gọi. */
+/** Build a message in call order. */
 export declare class Writer {
     private readonly parts;
     int(n: number, v: bigint | number | string): this;
     bytes(n: number, v: Buffer | string): this;
     msg(n: number, w: Writer): this;
-    /** `map<string,string>` theo đúng thứ tự khoá của object. */
+    /** `map<string,string>` in the object's key order. */
     map(n: number, obj: Record<string, string>): this;
     finish(): Buffer;
 }

package/dist/proto.js

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * Protobuf tối thiểu, không cần file `.proto`.
+ * Minimal protobuf, no `.proto` file needed.
  *
- * TikTok không công bố `.proto` của IM — số trường ở `constants.ts` dựng lại từ byte bắt được
- * trên trình duyệt (09/11/2026). Chỉ cần ba kiểu dây: varint (0), độ dài (2), và bỏ qua 1/5.
+ * TikTok doesn't publish its IM `.proto` — field numbers in `constants.ts` were reconstructed from bytes captured
+ * in the browser (09/11/2026). Only three wire types are needed: varint (0), length-delimited (2), and skipping 1/5.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Writer = exports.Msg = void 0;
@@ -14,14 +14,14 @@ function readVarint(b, i) {
     let c;
     do {
         if (i >= b.length)
-            throw new Error('varint vượt cuối buffer');
+            throw new Error('varint runs past end of buffer');
         c = b[i++];
         x |= BigInt(c & 127) << shift;
         shift += 7n;
     } while (c & 128);
     return [x, i];
 }
-/** Tách một message thành danh sách trường. `null` nếu byte không phải protobuf hợp lệ. */
+/** Split a message into a list of fields. `null` if the bytes are not valid protobuf. */
 function decodeFields(b) {
     const out = [];
     let i = 0;
@@ -63,7 +63,7 @@ function decodeFields(b) {
     }
     return out;
 }
-/** Message đã giải — đọc theo số trường. */
+/** Decoded message — read by field number. */
 class Msg {
     fields;
     constructor(fields) {
@@ -72,7 +72,7 @@ class Msg {
     static parse(b) {
         const f = decodeFields(b);
         if (!f)
-            throw new Error('Không giải được protobuf');
+            throw new Error('Failed to decode protobuf');
         return new Msg(f);
     }
     static tryParse(b) {
@@ -90,7 +90,7 @@ class Msg {
     num(n) {
         return Number(this.int(n));
     }
-    /** Số nguyên 64-bit dạng chuỗi — uid / mã tin vượt `Number.MAX_SAFE_INTEGER`. */
+    /** 64-bit integer as a string — uids / message IDs exceed `Number.MAX_SAFE_INTEGER`. */
     id(n) {
         return this.int(n).toString();
     }
@@ -112,7 +112,7 @@ class Msg {
             .map((f) => Msg.tryParse(f.bytes))
             .filter((m) => m !== null);
     }
-    /** `map<string,string>` — mỗi phần tử là message `{1: key, 2: value}`. */
+    /** `map<string,string>` — each entry is a message `{1: key, 2: value}`. */
     map(n) {
         const out = {};
         for (const m of this.msgs(n))
@@ -134,7 +134,7 @@ function varint(x) {
     return Buffer.from(out);
 }
 const key = (n, wire) => varint((BigInt(n) << 3n) | BigInt(wire));
-/** Ghép message theo thứ tự gọi. */
+/** Build a message in call order. */
 class Writer {
     parts = [];
     int(n, v) {
@@ -149,7 +149,7 @@ class Writer {
     msg(n, w) {
         return this.bytes(n, w.finish());
     }
-    /** `map<string,string>` theo đúng thứ tự khoá của object. */
+    /** `map<string,string>` in the object's key order. */
     map(n, obj) {
         for (const [k, v] of Object.entries(obj))
             this.msg(n, new Writer().bytes(1, k).bytes(2, v));

package/dist/qr-login.d.ts

@@ -1,41 +1,41 @@
 import type { Credentials } from './types';
 /**
- * Đăng nhập bằng QR qua Chrome headless.
+ * QR login via headless Chrome.
  *
- * Vì sao cần trình duyệt: API QR của TikTok (`passport/web/check_qrconnect`) đòi chữ ký JS
- * (X-Gnarly / msToken) — gọi trần từ Node bị `error_code 7`. Nên mở đúng trang
- * `tiktok.com/login/qrcode` trong Chrome headless để chính trang tự ký, còn mình chỉ NGHE
- * phản hồi qua CDP: ảnh QR lấy từ body `get_qrcode`, trạng thái từ body `check_qrconnect`.
- * Đăng nhập xong lấy cookie rồi tắt Chrome — mọi việc sau đó (`login`, chat) không cần trình duyệt.
+ * Why a browser: TikTok's QR API (`passport/web/check_qrconnect`) requires a JS signature
+ * (X-Gnarly / msToken) — calling it bare from Node yields `error_code 7`. So we open the real
+ * `tiktok.com/login/qrcode` page in headless Chrome and let it sign itself; we only LISTEN to
+ * responses via CDP: the QR image from the `get_qrcode` body, the status from `check_qrconnect`.
+ * After login we grab the cookies and close Chrome — everything after (`login`, chat) needs no browser.
  */
 export type QrLoginEvent = 
-/** Ảnh QR mới (`data:image/png;base64,…`) — hiện cho người dùng quét. Hết hạn thì có ảnh mới. */
+/** New QR image (`data:image/png;base64,…`) — show it to the user to scan. A new one comes on expiry. */
 {
     type: 'qr';
     image: string;
     expiresAt: number;
 }
-/** Đã quét, chờ bấm xác nhận trên điện thoại. */
+/** Scanned, waiting for confirmation on the phone. */
  | {
     type: 'scanned';
 }
-/** Đã xác nhận — đang lấy cookie. */
+/** Confirmed — fetching cookies. */
  | {
     type: 'confirmed';
 };
 export interface QrLoginOptions {
-    /** Đường dẫn Chrome / Chromium (vd `/usr/bin/chromium-browser`). */
+    /** Path to Chrome / Chromium (e.g. `/usr/bin/chromium-browser`). */
     chromePath: string;
     onEvent?: (e: QrLoginEvent) => void;
     signal?: AbortSignal;
-    /** Tổng thời gian chờ quét (ms) — mặc định 5 phút. */
+    /** Total time to wait for a scan (ms) — default 5 minutes. */
     timeoutMs?: number;
-    /** QR hết hạn (~1 phút) thì tạo lại tối đa chừng này lần. */
+    /** When the QR expires (~1 minute), regenerate it at most this many times. */
     maxRefresh?: number;
     userAgent?: string;
 }
 /**
- * Đăng nhập TikTok bằng QR. Trả `Credentials` (cookie `.tiktok.com` + UA) — đưa vào
- * `new TikTok().login(creds)` và LƯU LẠI để lần sau khỏi quét.
+ * Log in to TikTok via QR. Returns `Credentials` (`.tiktok.com` cookies + UA) — pass them to
+ * `new TikTok().login(creds)` and SAVE them so you don't need to scan next time.
  */
 export declare function loginQR(opts: QrLoginOptions): Promise<Credentials>;