tca-js 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rice2411
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# tca-js — Unofficial TikTok Chat API
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read and send TikTok **direct messages** (text, images, reactions) and receive new messages in real time over
+websocket — **using session cookies only, no browser needed**. Same idea as [`zca-js`](https://github.com/RFS-ADRENO/zca-js)
+for Zalo: it speaks the same protocol as TikTok Web (`tiktok.com/messages`, `tiktok.com/business-suite/messages`).
+
+> [!WARNING]
+> This is an **unofficial** library, not affiliated with or endorsed by TikTok / ByteDance. It relies on undocumented
+> internal APIs that can change or break at any time. Automating a TikTok account may violate TikTok's Terms of Service
+> and **can get the account restricted or banned** — use it at your own risk, don't spam.
+
+## Install
+
+```bash
+npm install tca-js
+```
+
+Node.js ≥ 22. QR login additionally needs a local Chrome / Chromium (see below); cookie login does not.
+
+## Quick start
+
+```ts
+import { TikTok, loginQR } from 'tca-js';
+
+const api = await new TikTok().login(await loginQR({ chromePath, onEvent }));  // or saved cookies
+api.listener.on('message', async (msg) => {
+  if (msg.isSelf) return;
+  if (msg.image) await api.downloadImage(msg);       // decrypted image Buffer
+  await api.sendMessage(msg, 'Got it, thanks!');     // a message carries its conversation
+});
+api.listener.start();                                 // reconnects on drop
+await api.sendImage(conv, { data: buf, filename: 'photo.jpg' });
+```
+
+## API
+
+| Method | Does |
+|---|---|
+| `loginQR({chromePath, onEvent, signal})` | QR login through headless Chrome → `Credentials` |
+| `new TikTok().login({cookies, deviceId?, userAgent?})` | validate cookies (`passport/web/account/info`), resolve `wid` as `device_id` → `API` |
+| `api.getConversations(cursor?)` | 10 conversations per page + latest message; page with `cursor` |
+| `api.getMessages(conv, {limit, before})` | messages of a conversation, newest → oldest |
+| `api.getUsers(uids)` | display name, `@username`, avatar |
+| `api.sendMessage(conv, text)` / `api.sendImage(conv, {data, filename})` | send |
+| `api.setReaction(msg, emoji \| null)` | your reaction on a message (one per user, `null` = remove); read via `msg.reactions` |
+| `api.downloadSticker(msg.sticker)` | sticker image (public CDN) |
+| `api.downloadImage(msg)` | download + decrypt AES-256-GCM (listener messages carry no link — looked up from history) |
+| `api.markRead(msg)` · `api.isAlive()` · `api.getCookies()` | |
+| `api.listener` | events `connected` · `message` · `command` (read receipts…) · `closed` · `error` |
+
+Errors: `TikTokError.code` — `SESSION_EXPIRED` (get fresh cookies), `IM_ERROR`, `UPLOAD_FAILED`, `DOWNLOAD_FAILED`, `HTTP_ERROR`.
+
+## Session — QR login and cookies
+
+```ts
+import { loginQR, TikTok } from 'tca-js';
+const creds = await loginQR({ chromePath: '/usr/bin/chromium-browser', onEvent: (e) => { /* qr | scanned | confirmed */ } });
+const api = await new TikTok().login(creds);   // SAVE creds (cookies) to skip scanning next time
+```
+
+- **Reading / sending / websocket only need cookies.** The `X-Gnarly`, `X-Dynosaur`, `X-Bogus`, `msToken` signatures
+  and `tt-ticket-guard-*` headers the page attaches to IM requests are **not checked** by the server.
+- **The QR login API (`passport/web/check_qrconnect`) DOES check signatures** — calling it bare from Node returns
+  `error_code 7`. So `loginQR` opens **headless Chrome/Chromium** at `tiktok.com/login/qrcode`, lets the page sign its
+  own requests, and only LISTENS via CDP: the QR image comes from the `get_qrcode` response, status
+  (`new → scanned → confirmed`, or `expired` → reload for a new QR) from `check_qrconnect`. Once confirmed it reads the
+  cookies (`Network.getAllCookies`) and closes Chrome. Works with `--no-sandbox` Chromium on Alpine.
+- Core cookies: `sessionid`, `sid_tt`, `sid_guard`, `uid_tt`, `ttwid`, `odin_tt`, `store-idc`, `tt-target-idc`.
+  `sessionid` lives ~6 months. TikTok allows concurrent sessions — logging in here doesn't kick other devices.
+- `device_id` = the `wid` TikTok issues for a `ttwid` (`/api/v1/web-cookie-privacy/config`). HTTP IM accepts any id
+  but **the websocket only accepts the real `wid`** (made-up id → 400).
+
+## Protocol (for fixing it when TikTok changes)
+
+**HTTP IM** — `POST https://im-api-sg.tiktok.com/<path>?aid=1988&…`, protobuf request and response.
+`Request {1 cmd, 2 seq, 3 sdk "1.8.5", 5 3, 6 0, 7 build, 8 {<cmd>: body}, 9 device_id, 11 "web", 15 map, 18 1}`,
+`Response {1 cmd, 3 status_code, 4 error, 6 {<cmd>: body}}` (`200005` = not logged in).
+
+| path | cmd | body |
+|---|---|---|
+| `/v1/message/send` | 100 | `{1 convId, 2 1, 3 shortId, 4 content JSON, 5 ext, 6 type, 7 "deprecated", 8 clientMsgId, [13 image, 14 "private_image", 17 image]}` |
+| `/v2/message/get_by_user_init` | 203 | `{1 offset}` → `{1 messages[], 2 conversations[], 4 next offset, 5 has more}` |
+| `/v1/message/get_by_conversation` | 301 | `{1 convId, 2 1, 3 shortId, 4 1 (older), 5 index anchor, 6 limit}` |
+| `/v3/conversation/mark_read` | 2002 (body at 604) | `{1 convId, 2 shortId, 3 1, 4 index, 11 4}` |
+| `/v1/media/upload_config` | 2059 | empty → ImageX STS keys |
+| `/v1/message/set_property` | 705 | `{1 {1 convId, 2 1, 3 shortId, 4 serverMsgId, 5 clientMsgId, 6 [{1 op 0 add/1 remove, 2 "e:<emoji>", 4 own uid}]}, 2 ticket}` → `{1 status (0 ok, 1 duplicate), 2 version}` |
+
+`MessageBody {1 convId, 3 serverMsgId, 4 index, 5 shortId, 6 type, 7 sender, 8 content JSON, 9 ext, 10 time ms, 15 reactions, 18 quote, 20 image/sticker}`.
+Types: `7` text (`{"aweType":0,"text":…}`), `1802` private image, `1805` sticker, `8` shared video, `1` system, `50001` hidden command.
+
+**Reactions** (field 15): `{1 "e:<emoji>", 2 {1 [{1 uid, 3 seconds, 4 idempotent_id, 6 µs}]}}`.
+The mobile app writes ❤️ as both `e:❤️` and the legacy `e:love` key (web ignores `e:love`) → `tca-js` merges them into ❤️.
+Web offers 12 emoji, one reaction per user (add the new key + remove your old one in the same 705 command).
+**Stickers** (`1805`, field 20 → 7): `{1 {1 uri, 2 public CDN url, 5 {w,h}}, 200 {1 {2 map a:sticker_id, a:sticker_type (14 stock / 15 custom)…}}}`.
+TikTok Web only DISPLAYS stickers, it has no send button — sending stickers is not implemented.
+1-1 `convId` = `0:1:<smaller uid>:<larger uid>`.
+
+**Websocket** — `wss://im-ws-sg.tiktok.com/ws/v2?aid=1459&fpid=9&access_key=…&device_id=<wid>&ttwid=…`
++ cookies. `access_key = md5("9" + "e1bd35ec9db7b8d846de66ed140b1ad9" + wid + "f8a69f1719916z")`.
+Frame `{1 seq, 2 logid, 3 5, 4 1, 5 headers, 6 encoding ("__lz4" = block compression), 7 "pb", 8 Response}`;
+new message = `Response.cmd 500`, `body[500][5]` is a `MessageBody`. Keep-alive: send text `"hi"` every 15 s.
+Frames with header `need_ack=1` → reply `{1 seq, 2 logid, 3 5, 4 1, 5 {is_ack:1, ack_id, ack_code:0}, 9 ack_id}`,
+`ack_id = <Date.now() base36>:<x_frontier_traceid>`. The server may push a message several times → dedupe by message id.
+
+**Sending images** — `upload_config` → ImageX signed with AWS SigV4 (`cn-north-1`/`imagex`): `ApplyImageUpload` →
+`POST https://<UploadHost>/upload/v1/<StoreUri>` (headers `Authorization: <Auth>`, `Content-CRC32`,
+**`X-Storage-U: <uid>`** — missing it gives 4004) → `CommitImageUpload` with `Functions: Encryption cipher_v2`
+→ returns `Uri` + `SecretKey` + dimensions → send message type `1802`.
+**Receiving images** — `p0-tiktok-dm-private-sg…` links (need cookies), content is AES-256-GCM:
+`12-byte IV ‖ ciphertext ‖ 16-byte tag`, key = `decrypt_key` (hex) in the message.
+
+## Re-discovering the protocol when it breaks
+
+Run Chrome with a debug port and capture traffic over CDP (`Network.*` for every target, including the chat iframe
+`tiktok.com/messages?scene=business`), then print the protobuf tree without a `.proto`. The web app's message bundle
+(`messages-vmok` manifest) ships full protobufjs schemas — the fastest way to find new commands. Requests the browser
+sends are the reference: rebuild them with `Writer`, drop the signatures, check the server still accepts them.
+
+## Development
+
+```bash
+npm install && npm run build
+node scripts/qr-login.mjs <chromePath> <output dir>   # try QR login (writes qr.png)
+node scripts/smoke.mjs --cookies <cookies.json> [--peer <uid>] [--text "…"] [--image <file>] [--listen 10]
+```
+
+`cookies.json` holds a real session — keep it out of the repo (already in `.gitignore`).
+
+Source comments are in Vietnamese. Issues and PRs welcome in English or Vietnamese.
+
+## License
+
+[MIT](LICENSE)

package/dist/api.d.ts

@@ -0,0 +1,75 @@
+import type { Context } from './context';
+import { Listener } from './listener';
+import type { ConversationPage, ConversationRef, ImageInput, MessagePage, TikTokAccount, TikTokImage, TikTokMessage, TikTokSticker, TikTokUser } from './types';
+/** Kết quả gửi: mã tin phía client (TikTok trả lại đúng mã này). Mã server tới qua listener (`isSelf`). */
+export interface SendResult {
+    clientMessageId: string;
+}
+/**
+ * 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.
+ */
+export declare class API {
+    private readonly ctx;
+    readonly account: TikTokAccount;
+    readonly listener: Listener;
+    private readonly media;
+    constructor(ctx: Context, account: TikTokAccount);
+    getOwnId(): string;
+    /** Cookie hiện tại — lưu lại để lần sau `login` không cần quét QR. */
+    getCookies(): {
+        name: string;
+        value: string;
+    }[];
+    getContext(): {
+        deviceId: string;
+        userAgent: string;
+    };
+    /** Phiên còn sống không — gọi định kỳ để phát hiện hết hạn sớm. */
+    isAlive(): Promise<boolean>;
+    /** Hội thoại gần đây + tin mới nhất của chúng, lật trang bằng `cursor`. */
+    getConversations(cursor?: string): Promise<ConversationPage>;
+    /** 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>`. */
+    getMessages(conv: ConversationRef, opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<MessagePage>;
+    /** Hồ sơ người dùng theo uid (tên hiển thị, @username, ảnh đại diện). */
+    getUsers(uids: string[]): Promise<TikTokUser[]>;
+    /**
+     * 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.
+     */
+    downloadAvatar(user: Pick<TikTokUser, 'avatars'>): Promise<{
+        data: Buffer;
+        type: string;
+    } | null>;
+    /** Đánh dấu đã đọc tới tin `msg`. */
+    markRead(msg: ConversationRef & {
+        index: string;
+    }): Promise<void>;
+    /** 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). */
+    sendMessage(conv: ConversationRef, text: string): Promise<SendResult>;
+    /** Gửi một ảnh: tải lên kho riêng tư (được mã hoá) rồi gửi tin ảnh. */
+    sendImage(conv: ConversationRef, image: ImageInput): Promise<SendResult>;
+    /**
+     * Đặ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.
+     */
+    setReaction(msg: TikTokMessage, emoji: string | null): Promise<void>;
+    /** Tải ảnh sticker (CDN công khai, không mã hoá, không cần cookie). */
+    downloadSticker(sticker: Pick<TikTokSticker, 'url'>): Promise<{
+        data: Buffer;
+        type: string;
+    }>;
+    /** 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). */
+    downloadImage(source: TikTokMessage | TikTokImage, which?: 'origin' | 'thumb'): Promise<Buffer>;
+    /** `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, …}. */
+    private send;
+}
+/** Tài khoản của cookie — `null` nếu cookie không còn đăng nhập. */
+export declare function fetchAccount(ctx: Context): Promise<TikTokAccount | null>;
+/** `wid` — mã máy TikTok cấp theo cookie `ttwid`; IM + websocket dùng làm `device_id`. */
+export declare function fetchWebId(ctx: Context): Promise<string>;
+export type { TikTokMessage };

package/dist/api.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.API = void 0;
+exports.fetchAccount = fetchAccount;
+exports.fetchWebId = fetchWebId;
+const node_crypto_1 = require("node:crypto");
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+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). */
+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.
+ */
+class API {
+    ctx;
+    account;
+    listener;
+    media;
+    constructor(ctx, account) {
+        this.ctx = ctx;
+        this.account = account;
+        this.listener = new listener_1.Listener(ctx);
+        this.media = new media_1.MediaClient(ctx);
+    }
+    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. */
+    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. */
+    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`. */
+    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: 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>`. */
+    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(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). */
+    async getUsers(uids) {
+        if (uids.length === 0)
+            return [];
+        const q = new URLSearchParams({
+            aid: '1988',
+            app_name: 'tiktok_web',
+            device_platform: 'web_pc',
+            source: 'im_chat',
+            from_page: 'message',
+            user_ids: JSON.stringify(uids),
+        });
+        const res = await this.ctx.getJson(`${constants_1.WEB}/tiktok/v1/im/user/profile/?${q}`);
+        if (res.status_code)
+            throw new errors_1.TikTokError('IM_ERROR', `user/profile: ${res.status_code}`, res.status_code);
+        return (res.users ?? []).map(({ im_user_profile: p = {} }) => ({
+            uid: p.user_id_str ?? '',
+            uniqueId: p.unique_id ?? '',
+            nickname: p.nick_name ?? '',
+            ...avatarLinks(p.avatars),
+        }));
+    }
+    /**
+     * 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.
+     */
+    async downloadAvatar(user) {
+        for (const url of user.avatars) {
+            const res = await fetch(url, {
+                headers: { 'User-Agent': this.ctx.userAgent },
+                referrerPolicy: 'no-referrer',
+                signal: AbortSignal.timeout(this.ctx.options.timeoutMs ?? 20_000),
+            }).catch(() => null);
+            const type = res?.headers.get('content-type') ?? '';
+            if (!res?.ok || !/^image\/(jpeg|png|webp|gif)/.test(type))
+                continue;
+            return { data: Buffer.from(await res.arrayBuffer()), type };
+        }
+        return null;
+    }
+    /** Đánh dấu đã đọc tới tin `msg`. */
+    async markRead(msg) {
+        await this.ctx.im('/v3/conversation/mark_read', constants_1.Cmd.MarkRead, new proto_1.Writer()
+            .bytes(1, msg.conversationId)
+            .int(2, BigInt(msg.conversationShortId))
+            .int(3, constants_1.ConversationType.OneToOne)
+            .int(4, BigInt(msg.index))
+            .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). */
+    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. */
+    async sendImage(conv, image) {
+        const up = await this.media.upload(image);
+        const cid = (0, node_crypto_1.randomUUID)();
+        const w = String(up.width);
+        const h = String(up.height);
+        const media = new proto_1.Writer()
+            .msg(1, new proto_1.Writer()
+            .bytes(1, up.uri)
+            .msg(5, new proto_1.Writer().int(1, up.width).int(2, up.height))
+            .bytes(6, up.secretKey)
+            .int(7, 0))
+            .msg(3, new proto_1.Writer()
+            .msg(1, new proto_1.Writer().bytes(1, 'You sent a 📷'))
+            .msg(2, new proto_1.Writer().bytes(1, 'sent a 📷'))
+            .msg(3, new proto_1.Writer().bytes(1, '[Photo]')))
+            .msg(200, new proto_1.Writer().msg(1, new proto_1.Writer().bytes(1, up.uri).map(2, {
+            image_width: w,
+            image_height: h,
+            decrypt_key: up.secretKey,
+            quote_preview: 'dm_cam_preview_photo',
+            sender_preview: 'sender_preview',
+        })));
+        const extra = new proto_1.Writer()
+            .msg(13, new proto_1.Writer().msg(4, media))
+            .bytes(14, 'private_image')
+            .msg(17, new proto_1.Writer()
+            .int(1, 1)
+            .bytes(2, up.uri)
+            .bytes(3, up.secretKey)
+            .msg(10, new proto_1.Writer().int(1, up.width).int(2, up.height).int(4, up.size).bytes(5, up.filename)));
+        await this.send(conv, cid, constants_1.MessageType.PrivateImage, '', extra);
+        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.
+     */
+    async setReaction(msg, emoji) {
+        const own = this.ctx.ownId;
+        const mine = msg.reactions.filter((r) => r.userIds.includes(own)).map((r) => r.emoji);
+        const ops = [];
+        if (emoji && !mine.includes(emoji))
+            ops.push({ op: constants_1.PropertyOp.Add, key: constants_1.REACTION_PREFIX + emoji });
+        for (const e of mine) {
+            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.
+            if (e === constants_1.REACTION_HEART)
+                ops.push({ op: constants_1.PropertyOp.Remove, key: constants_1.REACTION_LOVE_KEY });
+        }
+        if (ops.length === 0)
+            return;
+        const target = new proto_1.Writer()
+            .bytes(1, msg.conversationId)
+            .int(2, constants_1.ConversationType.OneToOne)
+            .int(3, BigInt(msg.conversationShortId))
+            .int(4, BigInt(msg.serverMessageId))
+            .bytes(5, msg.clientMessageId);
+        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.
+        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). */
+    async downloadSticker(sticker) {
+        const res = await fetch(sticker.url, {
+            headers: { 'User-Agent': this.ctx.userAgent },
+            referrerPolicy: 'no-referrer',
+            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'}`);
+        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). */
+    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.
+        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');
+        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, …}. */
+    async send(conv, cid, type, content, extra) {
+        if (!conv.conversationId || !conv.conversationShortId) {
+            throw new errors_1.TikTokError('IM_ERROR', 'Thiếu conversationId / conversationShortId');
+        }
+        const w = new proto_1.Writer()
+            .bytes(1, conv.conversationId)
+            .int(2, constants_1.ConversationType.OneToOne)
+            .int(3, BigInt(conv.conversationShortId))
+            .bytes(4, content)
+            .map(5, { 's:mentioned_users': '', 's:client_message_id': cid })
+            .int(6, type)
+            .bytes(7, 'deprecated')
+            .bytes(8, cid);
+        const body = extra ? Buffer.concat([w.finish(), extra.finish()]) : w.finish();
+        await this.ctx.im('/v1/message/send', constants_1.Cmd.SendMessage, body);
+    }
+}
+exports.API = API;
+/** Tài khoản của cookie — `null` nếu cookie không còn đăng nhập. */
+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)
+        return null;
+    return {
+        uid: res.data.user_id_str,
+        username: res.data.username ?? '',
+        screenName: res.data.screen_name ?? '',
+        avatar: res.data.avatar_url ?? '',
+    };
+}
+/**
+ * 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.
+ */
+function avatarLinks(avatars) {
+    const urls = [];
+    const walk = (v) => {
+        if (typeof v === 'string') {
+            if (/^https?:\/\//.test(v) && !urls.includes(v))
+                urls.push(v);
+        }
+        else if (Array.isArray(v))
+            v.forEach(walk);
+        else if (v && typeof v === 'object')
+            Object.values(v).forEach(walk);
+    };
+    walk(avatars);
+    const heic = (u) => /\.heic(\?|$)/i.test(u.split('?')[0] + '?');
+    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`. */
+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)
+        return '';
+    return /"wid":"(\d+)"/.exec(await res.text())?.[1] ?? '';
+}

package/dist/constants.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+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). */
+export declare const AID_WEB = "1988";
+/** App id kênh "frontier" — websocket đẩy tin mới. */
+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). */
+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`. */
+export declare const Cmd: {
+    readonly SendMessage: 100;
+    readonly GetMessagesByUserInit: 203;
+    readonly GetMessagesByConversation: 301;
+    /** Websocket đẩy tin mới. */
+    readonly NewMessage: 500;
+    /** Thả / gỡ reaction (`property` của tin) — `/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. */
+export declare const MARK_READ_BODY_FIELD = 604;
+/** `MessageBody.message_type`. */
+export declare const MessageType: {
+    readonly System: 1;
+    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á. */
+    readonly Sticker: 1805;
+    /** Lệnh ẩn (đã đọc…) — không hiện trong hội thoại, websocket vẫn đẩy. */
+    readonly Command: 50001;
+};
+export declare const ConversationType: {
+    readonly OneToOne: 1;
+};
+/** Trường của `Response` (cả HTTP lẫn payload websocket). */
+export declare const Resp: {
+    readonly cmd: 1;
+    readonly seq: 2;
+    readonly status: 3;
+    readonly error: 4;
+    readonly body: 6;
+    readonly logId: 7;
+};
+/** Trường của `MessageBody`. */
+export declare const MsgF: {
+    readonly conversationId: 1;
+    readonly conversationType: 2;
+    readonly serverMessageId: 3;
+    readonly indexInConversation: 4;
+    readonly conversationShortId: 5;
+    readonly type: 6;
+    readonly sender: 7;
+    readonly content: 8;
+    readonly ext: 9;
+    readonly createTime: 10;
+    /** `property_list` — reaction: `{1 khoá "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`). */
+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ư ❤️. */
+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). */
+export declare const IMAGEX_REGION = "cn-north-1";
+export declare const IMAGEX_SERVICE = "imagex";
+export declare const IMAGEX_VERSION = "2018-08-01";