tca-js 0.0.0-stage → 0.3.0

package/dist/constants.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Hằng giao thức IM của TikTok Web — dựng lại từ lưu lượng `tiktok.com/business-suite/messages`
+ * (09/11/2026). TikTok đổi phía họ thì sửa ở đây; ghi lại cách dò ra ở README.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMAGEX_VERSION = exports.IMAGEX_SERVICE = exports.IMAGEX_REGION = exports.REACTION_HEART = exports.REACTION_LOVE_KEY = exports.REACTION_PREFIX = exports.PropertyOp = exports.MsgF = exports.Resp = exports.ConversationType = exports.MessageType = exports.MARK_READ_BODY_FIELD = exports.Cmd = exports.FRONTIER_SALT = exports.FRONTIER_APP_KEY = exports.FRONTIER_FPID = exports.BUILD_NUMBER = exports.SDK_VERSION = exports.AID_FRONTIER = exports.AID_WEB = exports.DEFAULT_USER_AGENT = exports.WEB = exports.IM_WS = exports.IM_API = void 0;
+exports.IM_API = 'https://im-api-sg.tiktok.com';
+exports.IM_WS = 'wss://im-ws-sg.tiktok.com/ws/v2';
+exports.WEB = 'https://www.tiktok.com';
+exports.DEFAULT_USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36';
+/** App id của TikTok Web (HTTP IM). */
+exports.AID_WEB = '1988';
+/** App id kênh "frontier" — websocket đẩy tin mới. */
+exports.AID_FRONTIER = '1459';
+exports.SDK_VERSION = '1.8.5';
+exports.BUILD_NUMBER = 'feffaa1:master';
+/** `access_key` của websocket = md5(FPID + APP_KEY + device_id + SALT). */
+exports.FRONTIER_FPID = '9';
+exports.FRONTIER_APP_KEY = 'e1bd35ec9db7b8d846de66ed140b1ad9';
+exports.FRONTIER_SALT = 'f8a69f1719916z';
+/** Lệnh IM (`Request.cmd`) — đồng thời là số trường của body trong `RequestBody`. */
+exports.Cmd = {
+    SendMessage: 100,
+    GetMessagesByUserInit: 203,
+    GetMessagesByConversation: 301,
+    /** Websocket đẩy tin mới. */
+    NewMessage: 500,
+    /** Thả / gỡ reaction (`property` của tin) — `/v1/message/set_property`. */
+    SetMessageProperty: 705,
+    GetConversationInfo: 610,
+    MarkRead: 2002,
+    UploadConfig: 2059,
+};
+/** Body của MarkRead nằm ở trường 604, không trùng số lệnh. */
+exports.MARK_READ_BODY_FIELD = 604;
+/** `MessageBody.message_type`. */
+exports.MessageType = {
+    System: 1,
+    Text: 7,
+    ShareVideo: 8,
+    PrivateImage: 1802,
+    /** Sticker (nhãn dán) — ảnh công khai trên CDN sticker, không mã hoá. */
+    Sticker: 1805,
+    /** Lệnh ẩn (đã đọc…) — không hiện trong hội thoại, websocket vẫn đẩy. */
+    Command: 50001,
+};
+exports.ConversationType = { OneToOne: 1 };
+/** Trường của `Response` (cả HTTP lẫn payload websocket). */
+exports.Resp = { cmd: 1, seq: 2, status: 3, error: 4, body: 6, logId: 7 };
+/** Trường của `MessageBody`. */
+exports.MsgF = {
+    conversationId: 1,
+    conversationType: 2,
+    serverMessageId: 3,
+    indexInConversation: 4,
+    conversationShortId: 5,
+    type: 6,
+    sender: 7,
+    content: 8,
+    ext: 9,
+    createTime: 10,
+    /** `property_list` — reaction: `{1 khoá "e:<emoji>", 2 {1 PropertyItem[]}}`. */
+    propertyList: 15,
+    attachments: 20,
+    tag: 21,
+};
+/** Thao tác trên `property` của tin (`ModifyPropertyContent.operation`). */
+exports.PropertyOp = { Add: 0, Remove: 1 };
+/** Khoá reaction = `e:<emoji>`. App điện thoại thả ❤️ còn ghi thêm khoá cũ `e:love` — coi như ❤️. */
+exports.REACTION_PREFIX = 'e:';
+exports.REACTION_LOVE_KEY = 'e:love';
+exports.REACTION_HEART = '\u2764\uFE0F';
+/** ImageX — nơi tải ảnh lên (ký kiểu AWS SigV4). */
+exports.IMAGEX_REGION = 'cn-north-1';
+exports.IMAGEX_SERVICE = 'imagex';
+exports.IMAGEX_VERSION = '2018-08-01';

package/dist/context.d.ts

@@ -0,0 +1,32 @@
+import { Msg } from './proto';
+import type { Credentials, TikTokOptions } from './types';
+/** Cookie dạng `name → value` từ mọi kiểu đầu vào của `Credentials.cookies`. */
+export declare function normalizeCookies(input: Credentials['cookies']): Map<string, string>;
+/** Trạng thái dùng chung của một phiên: cookie, mã máy, uid, gọi HTTP. */
+export declare class Context {
+    readonly options: TikTokOptions;
+    readonly cookies: Map<string, string>;
+    /**
+     * Mã máy IM = `wid` TikTok cấp theo cookie `ttwid` (`login` tự hỏi). Websocket chỉ nhận đúng
+     * mã này — mã tự bịa bị 400 (HTTP IM thì không kén).
+     */
+    deviceId: string;
+    readonly userAgent: string;
+    ownId: string;
+    private seq;
+    constructor(creds: Credentials, options?: TikTokOptions);
+    cookieHeader(): string;
+    log(level: 'debug' | 'warn', msg: string): void;
+    /** `fetch` kèm cookie + UA + hạn chờ. */
+    fetch(url: string, init?: RequestInit & {
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+    getJson<T>(url: string): Promise<T>;
+    /** Vỏ `Request` của IM: lệnh + body + đầu mục chung. */
+    buildRequest(cmd: number, bodyField: number, body: Buffer): Buffer;
+    /**
+     * Gọi một lệnh IM qua HTTP. Trả body đã bóc (`ResponseBody[cmd]`).
+     * KHÔNG cần chữ ký X-Gnarly/X-Bogus/msToken — server IM chỉ xét cookie (thử 09/11/2026).
+     */
+    im(path: string, cmd: number, body: Buffer, bodyField?: number): Promise<Msg>;
+}

package/dist/context.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Context = void 0;
+exports.normalizeCookies = normalizeCookies;
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+const proto_1 = require("./proto");
+/** Cookie dạng `name → value` từ mọi kiểu đầu vào của `Credentials.cookies`. */
+function normalizeCookies(input) {
+    const jar = new Map();
+    if (typeof input === 'string') {
+        for (const part of input.split(';')) {
+            const i = part.indexOf('=');
+            if (i > 0)
+                jar.set(part.slice(0, i).trim(), part.slice(i + 1).trim());
+        }
+    }
+    else if (Array.isArray(input)) {
+        for (const c of input)
+            if (c?.name)
+                jar.set(c.name, String(c.value ?? ''));
+    }
+    else {
+        for (const [k, v] of Object.entries(input ?? {}))
+            jar.set(k, String(v));
+    }
+    return jar;
+}
+/** Trạng thái dùng chung của một phiên: cookie, mã máy, uid, gọi HTTP. */
+class Context {
+    options;
+    cookies;
+    /**
+     * Mã máy IM = `wid` TikTok cấp theo cookie `ttwid` (`login` tự hỏi). Websocket chỉ nhận đúng
+     * mã này — mã tự bịa bị 400 (HTTP IM thì không kén).
+     */
+    deviceId;
+    userAgent;
+    ownId = '';
+    seq = 10_000;
+    constructor(creds, options = {}) {
+        this.options = options;
+        this.cookies = normalizeCookies(creds.cookies);
+        this.deviceId = creds.deviceId ?? '';
+        this.userAgent = creds.userAgent || constants_1.DEFAULT_USER_AGENT;
+    }
+    cookieHeader() {
+        return [...this.cookies].map(([k, v]) => `${k}=${v}`).join('; ');
+    }
+    log(level, msg) {
+        this.options.logger?.(level, msg);
+    }
+    /** `fetch` kèm cookie + UA + hạn chờ. */
+    async fetch(url, init = {}) {
+        try {
+            return await fetch(url, {
+                ...init,
+                headers: {
+                    'User-Agent': this.userAgent,
+                    Referer: `${constants_1.WEB}/`,
+                    Origin: constants_1.WEB,
+                    Cookie: this.cookieHeader(),
+                    ...init.headers,
+                },
+                signal: AbortSignal.timeout(this.options.timeoutMs ?? 20_000),
+            });
+        }
+        catch (err) {
+            throw new errors_1.TikTokError('HTTP_ERROR', `${url.split('?')[0]}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    async getJson(url) {
+        const res = await this.fetch(url);
+        if (!res.ok)
+            throw new errors_1.TikTokError('HTTP_ERROR', `${url.split('?')[0]}: HTTP ${res.status}`, res.status);
+        return (await res.json());
+    }
+    /** Vỏ `Request` của IM: lệnh + body + đầu mục chung. */
+    buildRequest(cmd, bodyField, body) {
+        return new proto_1.Writer()
+            .int(1, cmd)
+            .int(2, this.seq++)
+            .bytes(3, constants_1.SDK_VERSION)
+            .bytes(4, '')
+            .int(5, 3)
+            .int(6, 0)
+            .bytes(7, constants_1.BUILD_NUMBER)
+            .msg(8, new proto_1.Writer().bytes(bodyField, body))
+            .bytes(9, this.deviceId)
+            .bytes(11, 'web')
+            .map(15, {
+            aid: constants_1.AID_WEB,
+            app_name: 'tiktok_web',
+            channel: 'web',
+            device_platform: 'web_pc',
+            device_id: this.deviceId,
+            user_is_login: 'true',
+            user_agent: this.userAgent,
+        })
+            .int(18, 1)
+            .finish();
+    }
+    /**
+     * Gọi một lệnh IM qua HTTP. Trả body đã bóc (`ResponseBody[cmd]`).
+     * KHÔNG cần chữ ký X-Gnarly/X-Bogus/msToken — server IM chỉ xét cookie (thử 09/11/2026).
+     */
+    async im(path, cmd, body, bodyField = cmd) {
+        const url = `${constants_1.IM_API}${path}?aid=${constants_1.AID_WEB}&version_code=1.0.0&app_name=tiktok_web&device_platform=web_pc`;
+        const res = await this.fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-protobuf', Accept: 'application/x-protobuf' },
+            body: new Uint8Array(this.buildRequest(cmd, bodyField, body)),
+        });
+        if (!res.ok)
+            throw new errors_1.TikTokError('HTTP_ERROR', `${path}: HTTP ${res.status}`, res.status);
+        const resp = proto_1.Msg.tryParse(Buffer.from(await res.arrayBuffer()));
+        if (!resp)
+            throw new errors_1.TikTokError('BAD_RESPONSE', `${path}: phản hồi không phải protobuf`);
+        const status = resp.num(constants_1.Resp.status);
+        if (status !== 0) {
+            const desc = resp.str(constants_1.Resp.error);
+            // Chưa đăng nhập: 200005 (thử bằng request không cookie).
+            const code = status === 200005 ? 'SESSION_EXPIRED' : 'IM_ERROR';
+            throw new errors_1.TikTokError(code, `${path}: ${status} ${desc}`.trim(), status);
+        }
+        return resp.msg(constants_1.Resp.body)?.msg(cmd) ?? resp.msg(constants_1.Resp.body)?.msg(bodyField) ?? proto_1.Msg.parse(Buffer.alloc(0));
+    }
+}
+exports.Context = Context;

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+/** Lỗi từ TikTok hoặc từ chính thư viện. `code` để bên dùng phân nhánh (vd phiên hết hạn → quét lại). */
+export declare class TikTokError extends Error {
+    readonly code: TikTokErrorCode;
+    /** Mã gốc TikTok trả (status_code / error_code) nếu có. */
+    readonly upstream?: number | string | undefined;
+    constructor(code: TikTokErrorCode, message: string, 
+    /** Mã gốc TikTok trả (status_code / error_code) nếu có. */
+    upstream?: number | string | undefined);
+}
+export type TikTokErrorCode = 
+/** Cookie không còn đăng nhập — phải lấy phiên mới. */
+'SESSION_EXPIRED' | 'HTTP_ERROR'
+/** IM trả `status_code` khác 0. */
+ | 'IM_ERROR' | 'UPLOAD_FAILED' | 'DOWNLOAD_FAILED' | 'BAD_RESPONSE'
+/** Đăng nhập QR không thành (Chrome không mở được, QR hết hạn, không thấy cookie…). */
+ | 'LOGIN_FAILED'
+/** Bên gọi huỷ đăng nhập QR (`signal`). */
+ | 'LOGIN_ABORTED';

package/dist/errors.js

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

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * tca — TikTok Chat API (giả lập TikTok Web), cùng ý tưởng với zca-js cho Zalo.
+ *
+ * ```ts
+ * const api = await new TikTok().login({ cookies, deviceId });
+ * api.listener.on('message', async (msg) => {
+ *   if (msg.isSelf) return;
+ *   await api.sendMessage(msg, 'Got it, thanks!');
+ * });
+ * 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.
+ */
+import { API } from './api';
+import type { Credentials, TikTokOptions } from './types';
+export declare class TikTok {
+    private readonly options;
+    constructor(options?: TikTokOptions);
+    /** Đăng nhập bằng cookie đã có. Cookie hết hạn → `TikTokError('SESSION_EXPIRED')`. */
+    login(credentials: Credentials): Promise<API>;
+}
+export { API } from './api';
+export type { SendResult } from './api';
+export { MessageType } from './constants';
+export { TikTokError } from './errors';
+export type { TikTokErrorCode } from './errors';
+export { Listener, MANUAL_CLOSE } from './listener';
+export { loginQR } from './qr-login';
+export type { QrLoginEvent, QrLoginOptions } from './qr-login';
+export type { ListenerEvents } from './listener';
+export type * from './types';

package/dist/index.js

@@ -0,0 +1,54 @@
+"use strict";
+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.
+ *
+ * ```ts
+ * const api = await new TikTok().login({ cookies, deviceId });
+ * api.listener.on('message', async (msg) => {
+ *   if (msg.isSelf) return;
+ *   await api.sendMessage(msg, 'Got it, thanks!');
+ * });
+ * 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.
+ */
+const api_1 = require("./api");
+const context_1 = require("./context");
+const errors_1 = require("./errors");
+class TikTok {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Đăng nhập bằng cookie đã có. Cookie hết hạn → `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');
+        }
+        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');
+        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?');
+        return new api_1.API(ctx, account);
+    }
+}
+exports.TikTok = TikTok;
+var api_2 = require("./api");
+Object.defineProperty(exports, "API", { enumerable: true, get: function () { return api_2.API; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "MessageType", { enumerable: true, get: function () { return constants_1.MessageType; } });
+var errors_2 = require("./errors");
+Object.defineProperty(exports, "TikTokError", { enumerable: true, get: function () { return errors_2.TikTokError; } });
+var listener_1 = require("./listener");
+Object.defineProperty(exports, "Listener", { enumerable: true, get: function () { return listener_1.Listener; } });
+Object.defineProperty(exports, "MANUAL_CLOSE", { enumerable: true, get: function () { return listener_1.MANUAL_CLOSE; } });
+var qr_login_1 = require("./qr-login");
+Object.defineProperty(exports, "loginQR", { enumerable: true, get: function () { return qr_login_1.loginQR; } });

package/dist/listener.d.ts

@@ -0,0 +1,43 @@
+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()`. */
+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`). */
+    message: [TikTokMessage];
+    /** Lệnh ẩn: đánh dấu đã đọc… (`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). */
+    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`.
+ */
+export declare class Listener extends EventEmitter<ListenerEvents> {
+    private readonly ctx;
+    private ws;
+    private heartbeat;
+    private idle;
+    private reconnectTimer;
+    private backoff;
+    private retry;
+    private readonly seen;
+    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. */
+    start(opts?: {
+        retryOnClose?: boolean;
+    }): void;
+    stop(): void;
+    private connect;
+    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. */
+    private ack;
+}

package/dist/listener.js

@@ -0,0 +1,181 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Listener = exports.MANUAL_CLOSE = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_events_1 = require("node:events");
+const ws_1 = __importDefault(require("ws"));
+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. */
+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. */
+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. */
+const DEDUPE_KEEP = 500;
+/** Mã đóng do chính mình gọi `stop()`. */
+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`.
+ */
+class Listener extends node_events_1.EventEmitter {
+    ctx;
+    ws = null;
+    heartbeat = null;
+    idle = null;
+    reconnectTimer = null;
+    backoff = RECONNECT_MIN_MS;
+    retry = true;
+    seen = new Set();
+    constructor(ctx) {
+        super();
+        this.ctx = ctx;
+    }
+    get connected() {
+        return this.ws?.readyState === ws_1.default.OPEN;
+    }
+    url() {
+        const accessKey = (0, node_crypto_1.createHash)('md5')
+            .update(constants_1.FRONTIER_FPID + constants_1.FRONTIER_APP_KEY + this.ctx.deviceId + constants_1.FRONTIER_SALT)
+            .digest('hex');
+        const q = new URLSearchParams({
+            aid: constants_1.AID_FRONTIER,
+            fpid: constants_1.FRONTIER_FPID,
+            device_platform: 'web',
+            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.
+            ttwid: decodeURIComponent(this.ctx.cookies.get('ttwid') ?? ''),
+            xsack: '1',
+            xaack: '1',
+            xsqos: '0',
+        });
+        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. */
+    start(opts = {}) {
+        this.retry = opts.retryOnClose ?? true;
+        this.connect();
+    }
+    stop() {
+        this.retry = false;
+        this.clearTimers();
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        const ws = this.ws;
+        this.ws = null;
+        if (ws && ws.readyState <= ws_1.default.OPEN)
+            ws.close(exports.MANUAL_CLOSE, 'manual');
+    }
+    connect() {
+        const ws = new ws_1.default(this.url(), {
+            headers: { Cookie: this.ctx.cookieHeader(), 'User-Agent': this.ctx.userAgent, Origin: constants_1.WEB },
+        });
+        this.ws = ws;
+        ws.binaryType = 'nodebuffer';
+        ws.on('open', () => {
+            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.emit('connected');
+        });
+        ws.on('message', (data, isBinary) => {
+            this.touch();
+            if (!isBinary)
+                return; // "hi" đáp lại
+            try {
+                this.onFrame(ws, data);
+            }
+            catch (err) {
+                this.emit('error', err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        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
+            this.ws = null;
+            this.clearTimers();
+            this.emit('closed', code, reason.toString());
+            if (!this.retry || code === exports.MANUAL_CLOSE)
+                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.reconnectTimer = setTimeout(() => this.connect(), wait);
+        });
+    }
+    touch() {
+        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.ws?.terminate();
+        }, IDLE_TIMEOUT_MS);
+    }
+    clearTimers() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        if (this.idle)
+            clearTimeout(this.idle);
+        this.heartbeat = null;
+        this.idle = null;
+    }
+    onFrame(ws, data) {
+        const m = proto_1.Msg.parse(data);
+        const frame = {
+            seq: m.int(1),
+            logId: m.int(2),
+            headers: m.map(5),
+            encoding: m.str(6),
+            payload: m.bytes(8),
+        };
+        if (frame.headers.need_ack === '1')
+            this.ack(ws, frame);
+        if (frame.payload.length === 0)
+            return;
+        const payload = frame.encoding === '__lz4' ? (0, lz4_1.lz4Decompress)(frame.payload) : frame.payload;
+        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}
+        const body = resp.msg(constants_1.Resp.body)?.msg(constants_1.Cmd.NewMessage)?.msg(5);
+        if (!body)
+            return;
+        const msg = (0, message_1.parseMessage)(body, this.ctx.ownId);
+        if (!msg.serverMessageId || this.seen.has(msg.serverMessageId))
+            return;
+        this.seen.add(msg.serverMessageId);
+        if (this.seen.size > DEDUPE_KEEP)
+            this.seen.delete(this.seen.values().next().value);
+        if (msg.kind === 'command')
+            this.emit('command', msg);
+        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. */
+    ack(ws, f) {
+        const ackId = `${Date.now().toString(36)}:${f.headers.x_frontier_traceid ?? ''}`;
+        const out = new proto_1.Writer()
+            .int(1, f.seq)
+            .int(2, f.logId)
+            .int(3, 5)
+            .int(4, 1)
+            .map(5, { is_ack: '1', ack_id: ackId, ack_code: '0' })
+            .bytes(9, ackId)
+            .finish();
+        if (ws.readyState === ws_1.default.OPEN)
+            ws.send(out);
+    }
+}
+exports.Listener = Listener;

package/dist/lz4.d.ts

@@ -0,0 +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.
+ */
+export declare function lz4Decompress(src: Buffer): Buffer;

package/dist/lz4.js

@@ -0,0 +1,57 @@
+"use strict";
+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.
+ */
+function lz4Decompress(src) {
+    let out = Buffer.alloc(Math.max(src.length * 4, 1024));
+    let o = 0;
+    const ensure = (need) => {
+        if (o + need <= out.length)
+            return;
+        let size = out.length * 2;
+        while (o + need > size)
+            size *= 2;
+        const bigger = Buffer.alloc(size);
+        out.copy(bigger, 0, 0, o);
+        out = bigger;
+    };
+    let i = 0;
+    while (i < src.length) {
+        const token = src[i++];
+        let lit = token >> 4;
+        if (lit === 15) {
+            let b;
+            do {
+                b = src[i++];
+                lit += b;
+            } while (b === 255);
+        }
+        ensure(lit);
+        src.copy(out, o, i, i + lit);
+        i += lit;
+        o += lit;
+        if (i >= src.length)
+            break;
+        const offset = src[i] | (src[i + 1] << 8);
+        i += 2;
+        if (offset === 0 || offset > o)
+            throw new Error('lz4: offset hỏng');
+        let len = token & 15;
+        if (len === 15) {
+            let b;
+            do {
+                b = src[i++];
+                len += b;
+            } while (b === 255);
+        }
+        len += 4;
+        ensure(len);
+        // Sao từng byte: vùng nguồn và đích được phép chồng nhau.
+        for (let k = 0; k < len; k++, o++)
+            out[o] = out[o - offset];
+    }
+    return out.subarray(0, o);
+}