tca-js 0.0.0-stage → 0.3.1

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,217 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+# tca-js
+
+**Unofficial TikTok Chat API for Node.js**
+
+Read and send TikTok direct messages, react, and receive new messages in real time.
+
+[![npm](https://img.shields.io/npm/v/tca-js)](https://www.npmjs.com/package/tca-js)
+[![license](https://img.shields.io/github/license/rice2411/tca-js)](LICENSE)
+[![node](https://img.shields.io/node/v/tca-js)](package.json)
+
+</div>
+
+> [!WARNING]
+> This project is not affiliated with or endorsed by TikTok / ByteDance. It relies on undocumented APIs that can change
+> at any time. Automating an account may violate TikTok's Terms of Service and can get it restricted — use at your own risk.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [API Reference](#api-reference)
+- [Listener](#listener)
+- [Error Handling](#error-handling)
+- [Contributing](#contributing)
+- [Support Us](#support-us)
+- [License](#license)
+
+## Features
+
+- 💬 Send text and image messages
+- 📥 List conversations, page through message history, look up users
+- ⚡ Real-time listener over websocket with auto-reconnect
+- 🖼️ Download and decrypt private images, download stickers and avatars
+- ❤️ Read and set reactions, mark conversations as read
+- 🔐 Cookie-based session — no browser at runtime
+- 📱 Optional QR-code login
+- 📦 Written in TypeScript, ships type definitions, one runtime dependency (`ws`)
+
+## Installation
+
+```bash
+npm install tca-js
+```
+
+Requires **Node.js 22+**. QR login also needs a local Chrome or Chromium; cookie login does not.
+
+## Quick Start
+
+```ts
+import { TikTok } from 'tca-js';
+
+const api = await new TikTok().login({ cookies });
+
+api.listener.on('message', async (msg) => {
+  if (msg.isSelf) return;
+  await api.sendMessage(msg, `You said: ${msg.text}`);
+});
+
+api.listener.start();
+```
+
+## Authentication
+
+### Cookies
+
+Log in with the cookies of a `tiktok.com` session. Accepted formats:
+
+```ts
+await new TikTok().login({ cookies: [{ name: 'sessionid', value: '…' }, /* … */] }); // array
+await new TikTok().login({ cookies: { sessionid: '…', ttwid: '…' } });              // object
+await new TikTok().login({ cookies: 'sessionid=…; ttwid=…' });                      // header string
+```
+
+Required cookies: `sessionid`, `sid_tt`, `sid_guard`, `uid_tt`, `ttwid`, `odin_tt`, `store-idc`, `tt-target-idc`.
+A session lasts about 6 months, and logging in does not sign out other devices.
+
+### QR code
+
+`loginQR` opens a headless Chrome on TikTok's QR page, emits the QR image, and resolves with credentials once the code is
+scanned and confirmed on the phone.
+
+```ts
+import { loginQR, TikTok } from 'tca-js';
+
+const credentials = await loginQR({
+  chromePath: '/usr/bin/chromium-browser',
+  onEvent: (e) => {
+    if (e.type === 'qr') showQr(e.image); // data:image/png;base64,…
+  },
+});
+
+const api = await new TikTok().login(credentials);
+// Save `credentials` to skip scanning next time.
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `chromePath` | `string` | — | Path to Chrome / Chromium |
+| `onEvent` | `(e) => void` | — | `qr` · `scanned` · `confirmed` |
+| `signal` | `AbortSignal` | — | Cancel the login |
+| `timeoutMs` | `number` | `300000` | Total time to wait for a scan |
+| `maxRefresh` | `number` | `3` | Max QR regenerations after expiry |
+| `userAgent` | `string` | — | Browser user agent |
+
+## API Reference
+
+`new TikTok(options?)` — `logger?: (level, msg) => void`, `timeoutMs?: number`.
+`.login(credentials)` resolves to an `API` instance.
+
+### Conversations & messages
+
+| Method | Returns | Description |
+|---|---|---|
+| `getConversations(cursor?)` | `ConversationPage` | 10 conversations per page with their latest messages |
+| `getMessages(conv, { limit?, before? })` | `MessagePage` | Messages of a conversation, newest first |
+| `sendMessage(conv, text)` | `SendResult` | Send a text message |
+| `sendImage(conv, { data, filename })` | `SendResult` | Send an image (`Buffer`) |
+| `setReaction(msg, emoji \| null)` | `void` | Set your reaction; `null` removes it |
+| `markRead(msg)` | `void` | Mark the conversation as read up to `msg` |
+
+`conv` is any object with `conversationId` and `conversationShortId` — every message satisfies it, so you can reply
+with `sendMessage(msg, …)`.
+
+### Users & media
+
+| Method | Returns | Description |
+|---|---|---|
+| `getUsers(uids)` | `TikTokUser[]` | Nickname, `@username`, avatar |
+| `downloadImage(msg, 'origin' \| 'thumb')` | `Buffer` | Download and decrypt a private image |
+| `downloadSticker(sticker)` | `{ data, type }` | Download a sticker image |
+| `downloadAvatar(user)` | `{ data, type } \| null` | Download a user's avatar |
+
+### Session
+
+| Method / property | Description |
+|---|---|
+| `account` | Logged-in account: `uid`, `username`, `screenName`, `avatar` |
+| `getOwnId()` | Own user id |
+| `getCookies()` | Current cookies — persist them to resume the session |
+| `isAlive()` | `true` while the session is still valid |
+
+### Message object
+
+| Field | Type | Description |
+|---|---|---|
+| `kind` | `'text' \| 'image' \| 'sticker' \| 'video' \| 'system' \| 'other'` | Message kind |
+| `text` | `string` | Text content |
+| `image` / `sticker` | `object \| null` | Attachment details |
+| `reactions` | `{ emoji, userIds }[]` | Reactions on the message |
+| `senderId` / `isSelf` | `string` / `boolean` | Sender |
+| `createdAt` | `number` | Epoch milliseconds |
+
+Full typings are shipped in `dist/index.d.ts`.
+
+## Listener
+
+```ts
+api.listener.on('connected', () => console.log('connected'));
+api.listener.on('message', (msg) => { /* new message */ });
+api.listener.on('command', (msg) => { /* read receipts and other hidden commands */ });
+api.listener.on('closed', (code, reason) => {});
+api.listener.on('error', (err) => {});
+
+api.listener.start();   // reconnects automatically; start({ retryOnClose: false }) to disable
+api.listener.stop();
+```
+
+## Error Handling
+
+All library errors are instances of `TikTokError` with a `code`:
+
+| Code | Meaning |
+|---|---|
+| `SESSION_EXPIRED` | Cookies are no longer valid — log in again |
+| `IM_ERROR` | TikTok rejected the request |
+| `HTTP_ERROR` · `BAD_RESPONSE` | Network or unexpected response |
+| `UPLOAD_FAILED` · `DOWNLOAD_FAILED` | Media transfer failed |
+| `LOGIN_FAILED` · `LOGIN_ABORTED` | QR login failed or was cancelled |
+
+```ts
+import { TikTokError } from 'tca-js';
+
+try {
+  await api.sendMessage(conv, 'hi');
+} catch (err) {
+  if (err instanceof TikTokError && err.code === 'SESSION_EXPIRED') {
+    // refresh credentials
+  }
+}
+```
+
+## Contributing
+
+Issues and pull requests are welcome. Protocol notes for maintainers are in [docs/PROTOCOL.md](docs/PROTOCOL.md).
+
+```bash
+npm install
+npm run build
+node scripts/smoke.mjs --cookies cookies.json   # read-only smoke test against a real account
+```
+
+## Support Us
+
+- ⭐ **Star the repository** if you find it useful
+- 🔄 **Share** it with others
+- 💡 **Contribute** ideas and code
+- ☕ **Buy me a coffee** — VietQR (MB Bank · `0776750418`)
+
+<img src=".github/assets/vietqr-mb.png" alt="VietQR MB Bank 0776750418" width="220">
+
+## License
+
+[MIT](LICENSE) © rice2411

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';
+/** Send result: client-side message id (TikTok echoes it back). The server id arrives via the listener (`isSelf`). */
+export interface SendResult {
+    clientMessageId: string;
+}
+/**
+ * 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.
+ */
+export declare class API {
+    private readonly ctx;
+    readonly account: TikTokAccount;
+    readonly listener: Listener;
+    private readonly media;
+    constructor(ctx: Context, account: TikTokAccount);
+    getOwnId(): string;
+    /** Current cookies — save them so the next `login` needs no QR scan. */
+    getCookies(): {
+        name: string;
+        value: string;
+    }[];
+    getContext(): {
+        deviceId: string;
+        userAgent: string;
+    };
+    /** Whether the session is still alive — call periodically to detect expiry early. */
+    isAlive(): Promise<boolean>;
+    /** Recent conversations + their latest messages, paginated with `cursor`. */
+    getConversations(cursor?: string): Promise<ConversationPage>;
+    /** Messages of a conversation, newest first. For older messages: `before = <index of oldest message>`. */
+    getMessages(conv: ConversationRef, opts?: {
+        limit?: number;
+        before?: string;
+    }): Promise<MessagePage>;
+    /** User profiles by uid (display name, @username, avatar). */
+    getUsers(uids: string[]): Promise<TikTokUser[]>;
+    /**
+     * 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.
+     */
+    downloadAvatar(user: Pick<TikTokUser, 'avatars'>): Promise<{
+        data: Buffer;
+        type: string;
+    } | null>;
+    /** Mark as read up to message `msg`. */
+    markRead(msg: ConversationRef & {
+        index: string;
+    }): Promise<void>;
+    /** Send a text message to a conversation (usually the just-received `msg` — it carries the conversation ids). */
+    sendMessage(conv: ConversationRef, text: string): Promise<SendResult>;
+    /** Send an image: upload to the private (encrypted) store, then send an image message. */
+    sendImage(conv: ConversationRef, image: ImageInput): Promise<SendResult>;
+    /**
+     * 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.
+     */
+    setReaction(msg: TikTokMessage, emoji: string | null): Promise<void>;
+    /** Download a sticker image (public CDN, unencrypted, no cookie needed). */
+    downloadSticker(sticker: Pick<TikTokSticker, 'url'>): Promise<{
+        data: Buffer;
+        type: string;
+    }>;
+    /** Download + decrypt a message's image (pass the whole `msg` — listener messages lack the URL, this looks it up). */
+    downloadImage(source: TikTokMessage | TikTokImage, which?: 'origin' | 'thumb'): Promise<Buffer>;
+    /** `SendMessageRequestBody`: {1 convId, 2 conversation type, 3 shortId, 4 content, 5 ext, 6 message type, 7 ticket, 8 client id, …}. */
+    private send;
+}
+/** Account for the cookie — `null` if the cookie is no longer logged in. */
+export declare function fetchAccount(ctx: Context): Promise<TikTokAccount | null>;
+/** `wid` — device id TikTok issues per `ttwid` cookie; IM + websocket use it as `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");
+/** "Latest" cursor for reading history — greater than any `index` (µs). */
+const NEWEST = 9999999999999999n;
+/**
+ * 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;
+    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;
+    }
+    /** 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 };
+    }
+    /** Whether the session is still alive — call periodically to detect expiry early. */
+    async isAlive() {
+        return (await fetchAccount(this.ctx).catch(() => null)) !== null;
+    }
+    // ─── 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)),
+            // 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,
+        };
+    }
+    /** 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) // 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 };
+    }
+    /** User profiles by uid (display name, @username, avatar). */
+    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),
+        }));
+    }
+    /**
+     * 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) {
+            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;
+    }
+    /** 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)
+            .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);
+    }
+    // ─── 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 };
+    }
+    /** 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)();
+        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 };
+    }
+    /**
+     * 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;
+        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 });
+            // ❤️ 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 });
+        }
+        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 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);
+    }
+    /** 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 },
+            referrerPolicy: 'no-referrer',
+            signal: AbortSignal.timeout(this.ctx.options.timeoutMs ?? 20_000),
+        }).catch(() => null);
+        if (!res?.ok)
+            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' };
+    }
+    /** 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;
+        // 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', 'Message has no image');
+        return this.media.download(image, which);
+    }
+    /** `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', 'Missing 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;
+/** 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)
+        return null;
+    return {
+        uid: res.data.user_id_str,
+        username: res.data.username ?? '',
+        screenName: res.data.screen_name ?? '',
+        avatar: res.data.avatar_url ?? '',
+    };
+}
+/**
+ * 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 = [];
+    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` — 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)
+        return '';
+    return /"wid":"(\d+)"/.exec(await res.text())?.[1] ?? '';
+}

package/dist/constants.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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";
+/** TikTok Web app id (HTTP IM). */
+export declare const AID_WEB = "1988";
+/** "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";
+/** 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";
+/** 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 push of new messages. */
+    readonly NewMessage: 500;
+    /** Add / remove a reaction (message `property`) — `/v1/message/set_property`. */
+    readonly SetMessageProperty: 705;
+    readonly GetConversationInfo: 610;
+    readonly MarkRead: 2002;
+    readonly UploadConfig: 2059;
+};
+/** 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: {
+    readonly System: 1;
+    readonly Text: 7;
+    readonly ShareVideo: 8;
+    readonly PrivateImage: 1802;
+    /** Sticker — public image on the sticker CDN, not encrypted. */
+    readonly Sticker: 1805;
+    /** Hidden command (read receipt…) — not shown in the conversation, but still pushed over websocket. */
+    readonly Command: 50001;
+};
+export declare const ConversationType: {
+    readonly OneToOne: 1;
+};
+/** `Response` fields (both HTTP and websocket payload). */
+export declare const Resp: {
+    readonly cmd: 1;
+    readonly seq: 2;
+    readonly status: 3;
+    readonly error: 4;
+    readonly body: 6;
+    readonly logId: 7;
+};
+/** `MessageBody` fields. */
+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 key "e:<emoji>", 2 {1 PropertyItem[]}}`. */
+    readonly propertyList: 15;
+    readonly attachments: 20;
+    readonly tag: 21;
+};
+/** Operation on a message `property` (`ModifyPropertyContent.operation`). */
+export declare const PropertyOp: {
+    readonly Add: 0;
+    readonly Remove: 1;
+};
+/** 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 — 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";