tca-js 0.3.0 → 0.4.0

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 };