tca-js 0.0.0-stage → 0.3.1

package/dist/constants.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * 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.
+ */
+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';
+/** TikTok Web app id (HTTP IM). */
+exports.AID_WEB = '1988';
+/** "frontier" channel app id — websocket pushing new messages. */
+exports.AID_FRONTIER = '1459';
+exports.SDK_VERSION = '1.8.5';
+exports.BUILD_NUMBER = 'feffaa1:master';
+/** Websocket `access_key` = md5(FPID + APP_KEY + device_id + SALT). */
+exports.FRONTIER_FPID = '9';
+exports.FRONTIER_APP_KEY = 'e1bd35ec9db7b8d846de66ed140b1ad9';
+exports.FRONTIER_SALT = 'f8a69f1719916z';
+/** IM command (`Request.cmd`) — also the body's field number in `RequestBody`. */
+exports.Cmd = {
+    SendMessage: 100,
+    GetMessagesByUserInit: 203,
+    GetMessagesByConversation: 301,
+    /** Websocket push of new messages. */
+    NewMessage: 500,
+    /** Add / remove a reaction (message `property`) — `/v1/message/set_property`. */
+    SetMessageProperty: 705,
+    GetConversationInfo: 610,
+    MarkRead: 2002,
+    UploadConfig: 2059,
+};
+/** MarkRead's body lives in field 604, not the command number. */
+exports.MARK_READ_BODY_FIELD = 604;
+/** `MessageBody.message_type`. */
+exports.MessageType = {
+    System: 1,
+    Text: 7,
+    ShareVideo: 8,
+    PrivateImage: 1802,
+    /** Sticker — public image on the sticker CDN, not encrypted. */
+    Sticker: 1805,
+    /** Hidden command (read receipt…) — not shown in the conversation, but still pushed over websocket. */
+    Command: 50001,
+};
+exports.ConversationType = { OneToOne: 1 };
+/** `Response` fields (both HTTP and websocket payload). */
+exports.Resp = { cmd: 1, seq: 2, status: 3, error: 4, body: 6, logId: 7 };
+/** `MessageBody` fields. */
+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 key "e:<emoji>", 2 {1 PropertyItem[]}}`. */
+    propertyList: 15,
+    attachments: 20,
+    tag: 21,
+};
+/** Operation on a message `property` (`ModifyPropertyContent.operation`). */
+exports.PropertyOp = { Add: 0, Remove: 1 };
+/** Reaction key = `e:<emoji>`. The mobile app reacting ❤️ also writes the legacy key `e:love` — treated as ❤️. */
+exports.REACTION_PREFIX = 'e:';
+exports.REACTION_LOVE_KEY = 'e:love';
+exports.REACTION_HEART = '\u2764\uFE0F';
+/** ImageX — image upload endpoint (AWS SigV4-style signing). */
+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';
+/** `name → value` cookies from any input shape of `Credentials.cookies`. */
+export declare function normalizeCookies(input: Credentials['cookies']): Map<string, string>;
+/** Shared state of a session: cookies, device id, uid, HTTP calls. */
+export declare class Context {
+    readonly options: TikTokOptions;
+    readonly cookies: Map<string, string>;
+    /**
+     * IM device id = the `wid` TikTok issues for the `ttwid` cookie (`login` fetches it). The websocket only
+     * accepts this id — a made-up id gets 400 (HTTP IM isn't picky).
+     */
+    deviceId: string;
+    readonly userAgent: string;
+    ownId: string;
+    private seq;
+    constructor(creds: Credentials, options?: TikTokOptions);
+    cookieHeader(): string;
+    log(level: 'debug' | 'warn', msg: string): void;
+    /** `fetch` with cookies + UA + timeout. */
+    fetch(url: string, init?: RequestInit & {
+        headers?: Record<string, string>;
+    }): Promise<Response>;
+    getJson<T>(url: string): Promise<T>;
+    /** IM `Request` envelope: command + body + common headers. */
+    buildRequest(cmd: number, bodyField: number, body: Buffer): Buffer;
+    /**
+     * Call an IM command over HTTP. Returns the unwrapped body (`ResponseBody[cmd]`).
+     * NO X-Gnarly/X-Bogus/msToken signature needed — the IM server only checks cookies (tested 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");
+/** `name → value` cookies from any input shape of `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;
+}
+/** Shared state of a session: cookies, device id, uid, HTTP calls. */
+class Context {
+    options;
+    cookies;
+    /**
+     * IM device id = the `wid` TikTok issues for the `ttwid` cookie (`login` fetches it). The websocket only
+     * accepts this id — a made-up id gets 400 (HTTP IM isn't picky).
+     */
+    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` with cookies + UA + timeout. */
+    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());
+    }
+    /** IM `Request` envelope: command + body + common headers. */
+    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();
+    }
+    /**
+     * Call an IM command over HTTP. Returns the unwrapped body (`ResponseBody[cmd]`).
+     * NO X-Gnarly/X-Bogus/msToken signature needed — the IM server only checks cookies (tested 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}: response is not protobuf`);
+        const status = resp.num(constants_1.Resp.status);
+        if (status !== 0) {
+            const desc = resp.str(constants_1.Resp.error);
+            // Not logged in: 200005 (tested with a cookieless request).
+            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 @@
+/** Error from TikTok or from the library itself. `code` lets callers branch (e.g. session expired → rescan). */
+export declare class TikTokError extends Error {
+    readonly code: TikTokErrorCode;
+    /** Original TikTok code (status_code / error_code), if any. */
+    readonly upstream?: number | string | undefined;
+    constructor(code: TikTokErrorCode, message: string, 
+    /** Original TikTok code (status_code / error_code), if any. */
+    upstream?: number | string | undefined);
+}
+export type TikTokErrorCode = 
+/** Cookie is no longer logged in — a new session is required. */
+'SESSION_EXPIRED' | 'HTTP_ERROR'
+/** IM returned a non-zero `status_code`. */
+ | 'IM_ERROR' | 'UPLOAD_FAILED' | 'DOWNLOAD_FAILED' | 'BAD_RESPONSE'
+/** QR login failed (Chrome failed to launch, QR expired, no cookie found…). */
+ | 'LOGIN_FAILED'
+/** Caller aborted QR login (`signal`). */
+ | 'LOGIN_ABORTED';

package/dist/errors.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TikTokError = void 0;
+/** Error from TikTok or from the library itself. `code` lets callers branch (e.g. session expired → rescan). */
+class TikTokError extends Error {
+    code;
+    upstream;
+    constructor(code, message, 
+    /** Original TikTok code (status_code / error_code), if any. */
+    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-js — unofficial TikTok Chat API (speaks the TikTok Web protocol).
+ *
+ * ```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();
+ * ```
+ *
+ * Getting cookies the first time: `loginQR({ chromePath, onEvent })` — opens headless Chrome on TikTok's QR page
+ * (the login API requires a JS signature so it can't be done in pure Node), returns cookies after scanning. See README.
+ */
+import { API } from './api';
+import type { Credentials, TikTokOptions } from './types';
+export declare class TikTok {
+    private readonly options;
+    constructor(options?: TikTokOptions);
+    /** Log in with existing cookies. Expired cookies → `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-js — unofficial TikTok Chat API (speaks the TikTok Web protocol).
+ *
+ * ```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();
+ * ```
+ *
+ * Getting cookies the first time: `loginQR({ chromePath, onEvent })` — opens headless Chrome on TikTok's QR page
+ * (the login API requires a JS signature so it can't be done in pure Node), returns cookies after scanning. See README.
+ */
+const api_1 = require("./api");
+const context_1 = require("./context");
+const errors_1 = require("./errors");
+class TikTok {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Log in with existing cookies. Expired cookies → `TikTokError('SESSION_EXPIRED')`. */
+    async login(credentials) {
+        const ctx = new context_1.Context(credentials, this.options);
+        if (!ctx.cookies.get('sessionid') && !ctx.cookies.get('sid_tt')) {
+            throw new errors_1.TikTokError('SESSION_EXPIRED', 'Cookie has no sessionid');
+        }
+        const account = await (0, api_1.fetchAccount)(ctx);
+        if (!account)
+            throw new errors_1.TikTokError('SESSION_EXPIRED', 'TikTok cookie is no longer logged in');
+        ctx.ownId = account.uid;
+        ctx.deviceId = (await (0, api_1.fetchWebId)(ctx).catch(() => '')) || ctx.deviceId;
+        if (!ctx.deviceId)
+            throw new errors_1.TikTokError('BAD_RESPONSE', 'Could not get wid (device_id) — cookie missing 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';
+/** Close code used when we call `stop()` ourselves. */
+export declare const MANUAL_CLOSE = 4000;
+export interface ListenerEvents {
+    connected: [];
+    /** A real message in a conversation (including our own — see `isSelf`). */
+    message: [TikTokMessage];
+    /** Hidden command: mark as read… (`content.command_type`). */
+    command: [TikTokMessage];
+    /** Close code + reason. Unless `MANUAL_CLOSE`, the listener reconnects automatically (if enabled). */
+    closed: [number, string];
+    error: [Error];
+}
+/**
+ * Listen for new messages via the `im-ws-sg` websocket (aid 1459) — cookies only.
+ * Events: `connected`, `message`, `closed`, `error`.
+ */
+export declare class Listener extends EventEmitter<ListenerEvents> {
+    private readonly ctx;
+    private ws;
+    private heartbeat;
+    private idle;
+    private reconnectTimer;
+    private backoff;
+    private retry;
+    private readonly seen;
+    constructor(ctx: Context);
+    get connected(): boolean;
+    url(): string;
+    /** Open the connection. `retryOnClose` (on by default): reconnect on drop, backing off up to 1 minute. */
+    start(opts?: {
+        retryOnClose?: boolean;
+    }): void;
+    stop(): void;
+    private connect;
+    private touch;
+    private clearTimers;
+    private onFrame;
+    /** Acknowledge receipt — `ack_id = <base36 time>:<x_frontier_traceid>`, echoing the frame's seq/logid. */
+    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");
+/** The browser sends "hi" every 15–30 seconds; use the lower bound. */
+const HEARTBEAT_MS = 15_000;
+/** If nothing (not even a "hi" reply) arrives for this long, treat it as silently dead and reconnect. */
+const IDLE_TIMEOUT_MS = 75_000;
+const RECONNECT_MIN_MS = 2_000;
+const RECONNECT_MAX_MS = 60_000;
+/** The server pushes the same message several times (one frame per device) — remember this many message IDs to dedupe. */
+const DEDUPE_KEEP = 500;
+/** Close code used when we call `stop()` ourselves. */
+exports.MANUAL_CLOSE = 4000;
+/**
+ * Listen for new messages via the `im-ws-sg` websocket (aid 1459) — cookies only.
+ * Events: `connected`, `message`, `closed`, `error`.
+ */
+class Listener extends node_events_1.EventEmitter {
+    ctx;
+    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,
+            // Cookie value is already URL-encoded (`1%7C…`) — decode it so URLSearchParams doesn't double-encode.
+            ttwid: decodeURIComponent(this.ctx.cookies.get('ttwid') ?? ''),
+            xsack: '1',
+            xaack: '1',
+            xsqos: '0',
+        });
+        return `${constants_1.IM_WS}?${q}`;
+    }
+    /** Open the connection. `retryOnClose` (on by default): reconnect on drop, backing off up to 1 minute. */
+    start(opts = {}) {
+        this.retry = opts.retryOnClose ?? true;
+        this.connect();
+    }
+    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 connected');
+            this.emit('connected');
+        });
+        ws.on('message', (data, isBinary) => {
+            this.touch();
+            if (!isBinary)
+                return; // "hi" reply
+            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; // old connection was replaced
+            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 closed (${code}) — reconnecting in ${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 silent too long — reconnecting');
+            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 type, 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);
+    }
+    /** Acknowledge receipt — `ack_id = <base36 time>:<x_frontier_traceid>`, echoing the frame's seq/logid. */
+    ack(ws, f) {
+        const ackId = `${Date.now().toString(36)}:${f.headers.x_frontier_traceid ?? ''}`;
+        const out = new proto_1.Writer()
+            .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 @@
+/**
+ * LZ4 block decompression (no frame header) — websocket frames with
+ * `payload_encoding = "__lz4"` compress their payload this way. No extra dependency for ~30 lines.
+ */
+export declare function lz4Decompress(src: Buffer): Buffer;

package/dist/lz4.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lz4Decompress = lz4Decompress;
+/**
+ * LZ4 block decompression (no frame header) — websocket frames with
+ * `payload_encoding = "__lz4"` compress their payload this way. No extra dependency for ~30 lines.
+ */
+function lz4Decompress(src) {
+    let out = Buffer.alloc(Math.max(src.length * 4, 1024));
+    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: invalid offset');
+        let len = token & 15;
+        if (len === 15) {
+            let b;
+            do {
+                b = src[i++];
+                len += b;
+            } while (b === 255);
+        }
+        len += 4;
+        ensure(len);
+        // Copy byte by byte: source and destination ranges may overlap.
+        for (let k = 0; k < len; k++, o++)
+            out[o] = out[o - offset];
+    }
+    return out.subarray(0, o);
+}