tca-js 0.3.1 → 0.4.0

package/README.md

@@ -25,6 +25,7 @@ Read and send TikTok direct messages, react, and receive new messages in real ti
 - [API Reference](#api-reference)
 - [Listener](#listener)
 - [Error Handling](#error-handling)
+- [Examples](#examples)
 - [Contributing](#contributing)
 - [Support Us](#support-us)
 - [License](#license)
@@ -38,7 +39,7 @@ Read and send TikTok direct messages, react, and receive new messages in real ti
 - ❤️ 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`)
+- 📦 Written in TypeScript, ships ESM + CommonJS builds with type definitions, one runtime dependency (`ws`)
 
 ## Installation
 
@@ -46,7 +47,14 @@ Read and send TikTok direct messages, react, and receive new messages in real ti
 npm install tca-js
 ```
 
-Requires **Node.js 22+**. QR login also needs a local Chrome or Chromium; cookie login does not.
+Requires **Node.js 22+**. Both ESM and CommonJS are supported:
+
+```ts
+import { TikTok } from 'tca-js'; // ESM / TypeScript
+const { TikTok } = require('tca-js'); // CommonJS
+```
+
+QR login also needs a local Chrome or Chromium; cookie login does not.
 
 ## Quick Start
 
@@ -70,9 +78,9 @@ api.listener.start();
 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
+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`.
@@ -87,7 +95,6 @@ scanned and confirmed on the phone.
 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,…
   },
@@ -97,14 +104,14 @@ 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 |
+| Option       | Type          | Default     | Description                                                                        |
+| ------------ | ------------- | ----------- | ---------------------------------------------------------------------------------- |
+| `chromePath` | `string`      | auto-detect | Path to Chrome / Chromium (falls back to `CHROME_PATH`, then common install paths) |
+| `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
 
@@ -113,46 +120,46 @@ const api = await new TikTok().login(credentials);
 
 ### 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` |
+| 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 |
+| 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 |
+| 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 |
+| 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`.
 
@@ -160,12 +167,16 @@ Full typings are shipped in `dist/index.d.ts`.
 
 ```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('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.start(); // reconnects automatically; start({ retryOnClose: false }) to disable
 api.listener.stop();
 ```
 
@@ -173,13 +184,13 @@ api.listener.stop();
 
 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 |
+| 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';
@@ -193,12 +204,19 @@ try {
 }
 ```
 
+## Examples
+
+- [`examples/qr-login.ts`](examples/qr-login.ts) — log in with a QR code and save the credentials to a file
+- [`examples/echo-bot.ts`](examples/echo-bot.ts) — reply to every incoming text message
+
 ## Contributing
 
-Issues and pull requests are welcome. Protocol notes for maintainers are in [docs/PROTOCOL.md](docs/PROTOCOL.md).
+Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Protocol notes for maintainers are in [docs/PROTOCOL.md](docs/PROTOCOL.md).
 
 ```bash
 npm install
+npm test                                        # unit tests (no network)
+npm run lint && npm run typecheck
 npm run build
 node scripts/smoke.mjs --cookies cookies.json   # read-only smoke test against a real account
 ```

package/dist/index.d.mts

@@ -0,0 +1,369 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Minimal protobuf, no `.proto` file needed.
+ *
+ * TikTok doesn't publish its IM `.proto` — field numbers in `constants.ts` were reconstructed from bytes captured
+ * in the browser (09/11/2026). Only three wire types are needed: varint (0), length-delimited (2), and skipping 1/5.
+ */
+interface Field {
+    n: number;
+    wire: number;
+    int: bigint;
+    bytes: Buffer;
+}
+/** Decoded message — read by field number. */
+declare class Msg {
+    readonly fields: Field[];
+    private constructor();
+    static parse(b: Buffer): Msg;
+    static tryParse(b: Buffer | undefined): Msg | null;
+    has(n: number): boolean;
+    int(n: number): bigint;
+    num(n: number): number;
+    /** 64-bit integer as a string — uids / message IDs exceed `Number.MAX_SAFE_INTEGER`. */
+    id(n: number): string;
+    bytes(n: number): Buffer;
+    str(n: number): string;
+    strs(n: number): string[];
+    msg(n: number): Msg | null;
+    msgs(n: number): Msg[];
+    /** `map<string,string>` — each entry is a message `{1: key, 2: value}`. */
+    map(n: number): Record<string, string>;
+}
+
+/** A cookie — same shape as `chrome.cookies.getAll` / CDP `Storage.getCookies` returns (extra fields are fine). */
+interface CookieInput {
+    name: string;
+    value: string;
+}
+/** What you need to log in again — save it after each login. */
+interface Credentials {
+    /** `.tiktok.com` cookies: array of `{name, value}`, object `{name: value}`, or string `a=b; c=d`. */
+    cookies: CookieInput[] | Record<string, string> | string;
+    /** IM device id (`wid`) — leave empty and `login` asks TikTok using `ttwid`. Only used when that fails. */
+    deviceId?: string;
+    userAgent?: string;
+}
+interface TikTokOptions {
+    /** Debug logging — silent by default. */
+    logger?: (level: 'debug' | 'warn', msg: string) => void;
+    /** Timeout per HTTP request (ms). */
+    timeoutMs?: number;
+}
+/** Enough to target a conversation: send, read, mark as read. Every `TikTokMessage` satisfies it. */
+interface ConversationRef {
+    conversationId: string;
+    conversationShortId: string;
+}
+interface TikTokImage {
+    /** Image id in TikTok storage (encrypted). */
+    uri: string;
+    /** Original download link — needs cookies, content is AES-256-GCM. */
+    url: string;
+    thumbUrl: string;
+    width: number;
+    height: number;
+    /** AES-256-GCM key (hex) to decrypt `url` — `api.downloadImage` handles this. */
+    decryptKey: string;
+}
+/** Sticker — including user-made stickers (`stickerType` 15). Public CDN link, signed + expires in a few days. */
+interface TikTokSticker {
+    stickerId: string;
+    /** 14 = built-in TikTok sticker, 15 = user-made sticker (memes, AI…). */
+    stickerType: number;
+    url: string;
+    width: number;
+    height: number;
+}
+/** A reaction on a message: emoji + users who reacted (uid). The mobile app's `e:love` is merged into ❤️. */
+interface TikTokReaction {
+    emoji: string;
+    userIds: string[];
+}
+interface TikTokMessage extends ConversationRef {
+    serverMessageId: string;
+    /** Position in the conversation (µs) — cursor for paging older messages. */
+    index: string;
+    /** `MessageType` — 7 text, 1802 image, 1805 sticker, 8 video share, 1 system. */
+    type: number;
+    /** `command` = hidden command (read receipt…) — listener emits it via the `command` event, not `message`. */
+    kind: 'text' | 'image' | 'sticker' | 'video' | 'system' | 'command' | 'other';
+    senderId: string;
+    isSelf: boolean;
+    /** Text content (`kind = text`), empty for other kinds. */
+    text: string;
+    image: TikTokImage | null;
+    sticker: TikTokSticker | null;
+    reactions: TikTokReaction[];
+    /** Raw JSON content (`{"aweType":0,"text":"…"}`…). */
+    content: unknown;
+    /** Send time, ms epoch. */
+    createdAt: number;
+    clientMessageId: string;
+    ext: Record<string, string>;
+}
+interface TikTokConversation extends ConversationRef {
+    participants: string[];
+    /** The other participant in a 1-1 conversation. */
+    peerId: string;
+}
+interface TikTokUser {
+    uid: string;
+    /** `@username` (without @). */
+    uniqueId: string;
+    nickname: string;
+    /** Best avatar (prefers jpeg/webp/png, avoids heic which browsers can't read). */
+    avatar: string;
+    /** All avatar links TikTok returns, by priority — signed, expiring links; `downloadAvatar` tries them in order. */
+    avatars: string[];
+}
+interface TikTokAccount {
+    uid: string;
+    username: string;
+    screenName: string;
+    avatar: string;
+}
+/** Image attachment. */
+interface ImageInput {
+    data: Buffer;
+    /** Only the extension matters so TikTok knows the format: `photo.jpg`, `bill.png`. */
+    filename: string;
+}
+interface MessagePage {
+    messages: TikTokMessage[];
+    hasMore: boolean;
+}
+interface ConversationPage {
+    conversations: TikTokConversation[];
+    /** Latest messages included — handy for building an inbox list. */
+    messages: TikTokMessage[];
+    cursor: string;
+    hasMore: boolean;
+}
+
+/** Shared state of a session: cookies, device id, uid, HTTP calls. */
+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>;
+}
+
+/** Close code used when we call `stop()` ourselves. */
+declare const MANUAL_CLOSE = 4000;
+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`.
+ */
+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;
+}
+
+/** Send result: client-side message id (TikTok echoes it back). The server id arrives via the listener (`isSelf`). */
+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.
+ */
+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>;
+    private send;
+}
+
+declare class TikTok {
+    private readonly options;
+    constructor(options?: TikTokOptions);
+    /** Log in with existing cookies. Expired cookies → `TikTokError('SESSION_EXPIRED')`. */
+    login(credentials: Credentials): Promise<API>;
+}
+
+/** `MessageBody.message_type`. */
+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;
+};
+
+/** Error from TikTok or from the library itself. `code` lets callers branch (e.g. session expired → rescan). */
+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);
+}
+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';
+
+/**
+ * QR login via headless Chrome.
+ *
+ * Why a browser: TikTok's QR API (`passport/web/check_qrconnect`) requires a JS signature
+ * (X-Gnarly / msToken) — calling it bare from Node yields `error_code 7`. So we open the real
+ * `tiktok.com/login/qrcode` page in headless Chrome and let it sign itself; we only LISTEN to
+ * responses via CDP: the QR image from the `get_qrcode` body, the status from `check_qrconnect`.
+ * After login we grab the cookies and close Chrome — everything after (`login`, chat) needs no browser.
+ */
+type QrLoginEvent = 
+/** New QR image (`data:image/png;base64,…`) — show it to the user to scan. A new one comes on expiry. */
+{
+    type: 'qr';
+    image: string;
+    expiresAt: number;
+}
+/** Scanned, waiting for confirmation on the phone. */
+ | {
+    type: 'scanned';
+}
+/** Confirmed — fetching cookies. */
+ | {
+    type: 'confirmed';
+};
+interface QrLoginOptions {
+    /**
+     * Path to Chrome / Chromium (e.g. `/usr/bin/chromium-browser`). Optional — when omitted, `CHROME_PATH` and the
+     * usual install locations are searched.
+     */
+    chromePath?: string;
+    onEvent?: (e: QrLoginEvent) => void;
+    signal?: AbortSignal;
+    /** Total time to wait for a scan (ms) — default 5 minutes. */
+    timeoutMs?: number;
+    /** When the QR expires (~1 minute), regenerate it at most this many times. */
+    maxRefresh?: number;
+    userAgent?: string;
+}
+/**
+ * Log in to TikTok via QR. Returns `Credentials` (`.tiktok.com` cookies + UA) — pass them to
+ * `new TikTok().login(creds)` and SAVE them so you don't need to scan next time.
+ */
+declare function loginQR(opts: QrLoginOptions): Promise<Credentials>;
+
+/**
+ * Locate a Chrome / Chromium executable: `CHROME_PATH` env, then well-known install paths for the platform, then
+ * `PATH`. Returns `null` when none is found.
+ */
+declare function findChrome(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string | null;
+
+export { API, Listener, MANUAL_CLOSE, MessageType, TikTok, TikTokError, findChrome, loginQR };
+export type { ConversationPage, ConversationRef, CookieInput, Credentials, ImageInput, ListenerEvents, MessagePage, QrLoginEvent, QrLoginOptions, SendResult, TikTokAccount, TikTokConversation, TikTokErrorCode, TikTokImage, TikTokMessage, TikTokOptions, TikTokReaction, TikTokSticker, TikTokUser };