tca-js 0.3.0 → 0.3.1

package/dist/qr-login.js

@@ -11,7 +11,7 @@ const node_path_1 = require("node:path");
 const ws_1 = __importDefault(require("ws"));
 const constants_1 = require("./constants");
 const errors_1 = require("./errors");
-/** Nối CDP vào một tab mới (một session phẳng trên websocket của trình duyệt). */
+/** Attach CDP to a new tab (a flat session on the browser websocket). */
 async function openTab(browserWs) {
     const ws = new ws_1.default(browserWs, { perMessageDeflate: false });
     await new Promise((resolve, reject) => {
@@ -50,7 +50,7 @@ async function openTab(browserWs) {
         close: () => ws.close(),
     };
 }
-/** Chạy Chrome headless, chờ dòng "DevTools listening on ws://…". */
+/** Launch headless Chrome and wait for the "DevTools listening on ws://…" line. */
 async function launchChrome(chromePath, userAgent) {
     const dir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'tca-chrome-'));
     const proc = (0, node_child_process_1.spawn)(chromePath, [
@@ -61,17 +61,17 @@ async function launchChrome(chromePath, userAgent) {
         '--no-default-browser-check',
         '--disable-gpu',
         '--disable-dev-shm-usage',
-        // Trong container chạy root — Chromium đòi tắt sandbox.
+        // Containers run as root — Chromium requires disabling the sandbox.
         '--no-sandbox',
         '--window-size=1280,900',
         '--lang=vi-VN',
-        // UA mặc định của headless có chữ "HeadlessChrome" — thay bằng UA thường.
+        // The default headless UA contains "HeadlessChrome" — replace it with a normal UA.
         `--user-agent=${userAgent}`,
         'about:blank',
     ], { stdio: ['ignore', 'ignore', 'pipe'] });
     const ws = await new Promise((resolve, reject) => {
         let buf = '';
-        const timer = setTimeout(() => reject(new Error('Chrome không khởi động sau 20s')), 20_000);
+        const timer = setTimeout(() => reject(new Error('Chrome did not start within 20s')), 20_000);
         proc.stderr.on('data', (d) => {
             buf += d.toString();
             const m = /DevTools listening on (ws:\/\/\S+)/.exec(buf);
@@ -86,18 +86,18 @@ async function launchChrome(chromePath, userAgent) {
         });
         proc.once('exit', (code) => {
             clearTimeout(timer);
-            reject(new Error(`Chrome thoát (${code}) trước khi sẵn sàng`));
+            reject(new Error(`Chrome exited (${code}) before it was ready`));
         });
     }).catch(async (err) => {
         proc.kill('SIGKILL');
         await (0, promises_1.rm)(dir, { recursive: true, force: true });
-        throw new errors_1.TikTokError('LOGIN_FAILED', `Không mở được Chrome: ${err instanceof Error ? err.message : String(err)}`);
+        throw new errors_1.TikTokError('LOGIN_FAILED', `Failed to launch Chrome: ${err instanceof Error ? err.message : String(err)}`);
     });
     return { proc, ws, dir };
 }
 /**
- * Đă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.
  */
 async function loginQR(opts) {
     const userAgent = opts.userAgent || constants_1.DEFAULT_USER_AGENT;
@@ -125,8 +125,8 @@ async function loginQR(opts) {
                 else
                     resolve(creds);
             };
-            const timer = setTimeout(() => finish(new errors_1.TikTokError('LOGIN_FAILED', 'Hết thời gian chờ quét QR')), opts.timeoutMs ?? 5 * 60_000);
-            const onAbort = () => finish(new errors_1.TikTokError('LOGIN_ABORTED', 'Đã huỷ đăng nhập QR'));
+            const timer = setTimeout(() => finish(new errors_1.TikTokError('LOGIN_FAILED', 'Timed out waiting for QR scan')), opts.timeoutMs ?? 5 * 60_000);
+            const onAbort = () => finish(new errors_1.TikTokError('LOGIN_ABORTED', 'QR login aborted'));
             opts.signal?.addEventListener('abort', onAbort);
             const body = async (requestId) => {
                 const r = await tab.send('Network.getResponseBody', { requestId }).catch(() => null);
@@ -139,13 +139,13 @@ async function loginQR(opts) {
                     return null;
                 }
             };
-            /** Sau `confirmed`: trang tự chuyển hướng + đặt cookie phiên — chờ có `sessionid`. */
+            /** After `confirmed`: the page redirects and sets session cookies — wait for `sessionid`. */
             const collectCookies = async () => {
                 for (let i = 0; i < 30 && !done; i++) {
                     const { cookies } = await tab.send('Network.getAllCookies');
                     const mine = cookies.filter((c) => c.domain.endsWith('tiktok.com'));
                     if (mine.some((c) => c.name === 'sessionid' && c.value) && mine.some((c) => c.name === 'ttwid')) {
-                        // Trùng tên ở `.tiktok.com` và `www.tiktok.com` → giữ bản `.tiktok.com`.
+                        // Same name on `.tiktok.com` and `www.tiktok.com` → keep the `.tiktok.com` one.
                         const byName = new Map();
                         for (const c of mine.sort((a, b) => (a.domain === '.tiktok.com' ? 1 : 0) - (b.domain === '.tiktok.com' ? 1 : 0))) {
                             byName.set(c.name, { name: c.name, value: c.value });
@@ -154,7 +154,7 @@ async function loginQR(opts) {
                     }
                     await new Promise((r) => setTimeout(r, 1000));
                 }
-                finish(new errors_1.TikTokError('LOGIN_FAILED', 'Đã xác nhận nhưng không thấy cookie sessionid'));
+                finish(new errors_1.TikTokError('LOGIN_FAILED', 'Confirmed but no sessionid cookie found'));
             };
             tab.on((method, p) => {
                 if (done)
@@ -180,7 +180,7 @@ async function loginQR(opts) {
                     });
                 }
                 else if (url.includes('/passport/web/check_qrconnect/')) {
-                    // Trang hỏi song song 3 vùng (sg/us/eu) — chỉ vùng của tài khoản đổi trạng thái, còn lại vẫn "new".
+                    // The page polls 3 regions in parallel (sg/us/eu) — only the account's region changes status, the rest stay "new".
                     void body(p.requestId).then((j) => {
                         const status = String(j?.data?.status ?? '');
                         if (status === 'scanned' && !scanned) {
@@ -193,7 +193,7 @@ async function loginQR(opts) {
                         }
                         else if (status === 'expired' && !scanned) {
                             if (refreshes++ >= maxRefresh)
-                                finish(new errors_1.TikTokError('LOGIN_FAILED', 'QR hết hạn, không ai quét'));
+                                finish(new errors_1.TikTokError('LOGIN_FAILED', 'QR expired without being scanned'));
                             else
                                 void tab.send('Page.reload');
                         }

package/dist/types.d.ts

@@ -1,87 +1,87 @@
-/** Một cookie — đúng dạng `chrome.cookies.getAll` / CDP `Storage.getCookies` trả về (thừa trường không sao). */
+/** A cookie — same shape as `chrome.cookies.getAll` / CDP `Storage.getCookies` returns (extra fields are fine). */
 export interface CookieInput {
     name: string;
     value: string;
 }
-/** Thứ cần để đăng nhập lại — lưu lại sau mỗi lần đăng nhập, như `{cookie, imei, userAgent}` của zca-js. */
+/** What you need to log in again — save it after each login. */
 export interface Credentials {
-    /** Cookie của `.tiktok.com`: mảng `{name, value}`, object `{name: value}`, hoặc chuỗi `a=b; c=d`. */
+    /** `.tiktok.com` cookies: array of `{name, value}`, object `{name: value}`, or string `a=b; c=d`. */
     cookies: CookieInput[] | Record<string, string> | string;
-    /** Mã máy IM (`wid`) — bỏ trống thì `login` hỏi TikTok theo `ttwid`. Chỉ dùng khi không hỏi được. */
+    /** IM device id (`wid`) — leave empty and `login` asks TikTok using `ttwid`. Only used when that fails. */
     deviceId?: string;
     userAgent?: string;
 }
 export interface TikTokOptions {
-    /** Ghi log gỡ lỗi — mặc định im lặng. */
+    /** Debug logging — silent by default. */
     logger?: (level: 'debug' | 'warn', msg: string) => void;
-    /** Hạn chờ mỗi request HTTP (ms). */
+    /** Timeout per HTTP request (ms). */
     timeoutMs?: number;
 }
-/** Đủ để nhắm một hội thoại: gửi tin, đọc tin, đánh dấu đã đọc. Mọi `TikTokMessage` đều thoả. */
+/** Enough to target a conversation: send, read, mark as read. Every `TikTokMessage` satisfies it. */
 export interface ConversationRef {
     conversationId: string;
     conversationShortId: string;
 }
 export interface TikTokImage {
-    /** Mã ảnh trên kho TikTok (đã mã hoá). */
+    /** Image id in TikTok storage (encrypted). */
     uri: string;
-    /** Link tải bản gốc — cần cookie, nội dung là AES-256-GCM. */
+    /** Original download link — needs cookies, content is AES-256-GCM. */
     url: string;
     thumbUrl: string;
     width: number;
     height: number;
-    /** Khoá AES-256-GCM (hex) để giải `url` — `api.downloadImage` lo việc này. */
+    /** AES-256-GCM key (hex) to decrypt `url` — `api.downloadImage` handles this. */
     decryptKey: string;
 }
-/** Sticker (nhãn dán) — kể cả sticker khách tự tạo (`stickerType` 15). Link CDN công khai, có chữ ký + hạn vài ngày. */
+/** Sticker — including user-made stickers (`stickerType` 15). Public CDN link, signed + expires in a few days. */
 export interface TikTokSticker {
     stickerId: string;
-    /** 14 = sticker có sẵn của TikTok, 15 = sticker người dùng tự tạo (ảnh chế, AI…). */
+    /** 14 = built-in TikTok sticker, 15 = user-made sticker (memes, AI…). */
     stickerType: number;
     url: string;
     width: number;
     height: number;
 }
-/** Một reaction trên tin: emoji + những người đã thả (uid). `e:love` của app điện thoại đã gộp vào ❤️. */
+/** A reaction on a message: emoji + users who reacted (uid). The mobile app's `e:love` is merged into ❤️. */
 export interface TikTokReaction {
     emoji: string;
     userIds: string[];
 }
 export interface TikTokMessage extends ConversationRef {
     serverMessageId: string;
-    /** Vị trí trong hội thoại (µs) — làm mốc đọc tiếp tin cũ hơn. */
+    /** Position in the conversation (µs) — cursor for paging older messages. */
     index: string;
-    /** `MessageType` — 7 chữ, 1802 ảnh, 1805 sticker, 8 chia sẻ video, 1 hệ thống. */
+    /** `MessageType` — 7 text, 1802 image, 1805 sticker, 8 video share, 1 system. */
     type: number;
-    /** `command` = lệnh ẩn (đã đọc…) — listener phát qua sự kiện `command`, không qua `message`. */
+    /** `command` = hidden command (read receipt…) — listener emits it via the `command` event, not `message`. */
     kind: 'text' | 'image' | 'sticker' | 'video' | 'system' | 'command' | 'other';
     senderId: string;
     isSelf: boolean;
-    /** Nội dung chữ (`kind = text`), rỗng với loại khác. */
+    /** Text content (`kind = text`), empty for other kinds. */
     text: string;
     image: TikTokImage | null;
     sticker: TikTokSticker | null;
     reactions: TikTokReaction[];
-    /** JSON thô của nội dung (`{"aweType":0,"text":"…"}`…). */
+    /** Raw JSON content (`{"aweType":0,"text":"…"}`…). */
     content: unknown;
-    /** Giờ gửi, ms epoch. */
+    /** Send time, ms epoch. */
     createdAt: number;
     clientMessageId: string;
     ext: Record<string, string>;
 }
 export interface TikTokConversation extends ConversationRef {
     participants: string[];
-    /** Người còn lại trong hội thoại 1-1. */
+    /** The other participant in a 1-1 conversation. */
     peerId: string;
 }
 export interface TikTokUser {
     uid: string;
-    /** `@username` (không có @). */
+    /** `@username` (without @). */
     uniqueId: string;
     nickname: string;
-    /** Ảnh đại diện tốt nhất (ưu tiên jpeg/webp/png, tránh heic trình duyệt không đọc). */
+    /** Best avatar (prefers jpeg/webp/png, avoids heic which browsers can't read). */
     avatar: string;
-    /** Mọi link ảnh đại diện TikTok trả, xếp theo ưu tiên — link có chữ ký, có hạn; `downloadAvatar` thử lần lượt. */
+    /** All avatar links TikTok returns, by priority — signed, expiring links; `downloadAvatar` tries them in order. */
     avatars: string[];
 }
 export interface TikTokAccount {
@@ -90,10 +90,10 @@ export interface TikTokAccount {
     screenName: string;
     avatar: string;
 }
-/** File đính kèm — giống `attachments` của zca-js. */
+/** Image attachment. */
 export interface ImageInput {
     data: Buffer;
-    /** Chỉ cần đuôi để TikTok biết định dạng: `anh.jpg`, `bill.png`. */
+    /** Only the extension matters so TikTok knows the format: `photo.jpg`, `bill.png`. */
     filename: string;
 }
 export interface MessagePage {
@@ -102,7 +102,7 @@ export interface MessagePage {
 }
 export interface ConversationPage {
     conversations: TikTokConversation[];
-    /** Tin mới nhất kèm theo — tiện dựng danh sách hộp thư. */
+    /** Latest messages included — handy for building an inbox list. */
     messages: TikTokMessage[];
     cursor: string;
     hasMore: boolean;

package/package.json

@@ -1,17 +1,35 @@
 {
   "name": "tca-js",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Unofficial TikTok Chat API for JavaScript — read/send TikTok direct messages (text, images, reactions) and listen over websocket using session cookies, no browser needed.",
   "license": "MIT",
   "author": "rice2411",
-  "repository": { "type": "git", "url": "git+https://github.com/rice2411/tca-js.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rice2411/tca-js.git"
+  },
   "homepage": "https://github.com/rice2411/tca-js#readme",
-  "bugs": { "url": "https://github.com/rice2411/tca-js/issues" },
-  "keywords": ["tiktok", "tiktok-api", "tiktok-dm", "tiktok-chat", "direct-message", "unofficial", "chat", "websocket", "zca-js"],
+  "bugs": {
+    "url": "https://github.com/rice2411/tca-js/issues"
+  },
+  "keywords": [
+    "tiktok",
+    "tiktok-api",
+    "tiktok-dm",
+    "tiktok-chat",
+    "direct-message",
+    "unofficial",
+    "chat",
+    "websocket"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist"],
-  "engines": { "node": ">=22" },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",