tca-js 0.0.0-stage → 0.3.1

package/dist/qr-login.js

@@ -0,0 +1,212 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loginQR = loginQR;
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const ws_1 = __importDefault(require("ws"));
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+/** Attach CDP to a new tab (a flat session on the browser websocket). */
+async function openTab(browserWs) {
+    const ws = new ws_1.default(browserWs, { perMessageDeflate: false });
+    await new Promise((resolve, reject) => {
+        ws.once('open', () => resolve());
+        ws.once('error', reject);
+    });
+    let id = 0;
+    let sessionId;
+    const pending = new Map();
+    const handlers = [];
+    ws.on('message', (raw) => {
+        const m = JSON.parse(raw.toString());
+        if (m.id !== undefined && pending.has(m.id)) {
+            const p = pending.get(m.id);
+            pending.delete(m.id);
+            if (m.error)
+                p.reject(new Error(m.error.message));
+            else
+                p.resolve(m.result ?? {});
+            return;
+        }
+        if (m.method && (!m.sessionId || m.sessionId === sessionId))
+            for (const h of handlers)
+                h(m.method, m.params ?? {});
+    });
+    const raw = (method, params = {}, sid) => new Promise((resolve, reject) => {
+        const i = ++id;
+        pending.set(i, { resolve: resolve, reject });
+        ws.send(JSON.stringify({ id: i, method, params, ...(sid ? { sessionId: sid } : {}) }));
+    });
+    const target = await raw('Target.createTarget', { url: 'about:blank' });
+    sessionId = (await raw('Target.attachToTarget', { targetId: target.targetId, flatten: true })).sessionId;
+    return {
+        send: (method, params) => raw(method, params, sessionId),
+        on: (h) => handlers.push(h),
+        close: () => ws.close(),
+    };
+}
+/** Launch headless Chrome and wait for the "DevTools listening on ws://…" line. */
+async function launchChrome(chromePath, userAgent) {
+    const dir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'tca-chrome-'));
+    const proc = (0, node_child_process_1.spawn)(chromePath, [
+        '--headless=new',
+        '--remote-debugging-port=0',
+        `--user-data-dir=${dir}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--disable-gpu',
+        '--disable-dev-shm-usage',
+        // Containers run as root — Chromium requires disabling the sandbox.
+        '--no-sandbox',
+        '--window-size=1280,900',
+        '--lang=vi-VN',
+        // The default headless UA contains "HeadlessChrome" — replace it with a normal UA.
+        `--user-agent=${userAgent}`,
+        'about:blank',
+    ], { stdio: ['ignore', 'ignore', 'pipe'] });
+    const ws = await new Promise((resolve, reject) => {
+        let buf = '';
+        const timer = setTimeout(() => reject(new Error('Chrome did not start within 20s')), 20_000);
+        proc.stderr.on('data', (d) => {
+            buf += d.toString();
+            const m = /DevTools listening on (ws:\/\/\S+)/.exec(buf);
+            if (m) {
+                clearTimeout(timer);
+                resolve(m[1]);
+            }
+        });
+        proc.once('error', (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+        proc.once('exit', (code) => {
+            clearTimeout(timer);
+            reject(new Error(`Chrome exited (${code}) before it was ready`));
+        });
+    }).catch(async (err) => {
+        proc.kill('SIGKILL');
+        await (0, promises_1.rm)(dir, { recursive: true, force: true });
+        throw new errors_1.TikTokError('LOGIN_FAILED', `Failed to launch Chrome: ${err instanceof Error ? err.message : String(err)}`);
+    });
+    return { proc, ws, dir };
+}
+/**
+ * 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.
+ */
+async function loginQR(opts) {
+    const userAgent = opts.userAgent || constants_1.DEFAULT_USER_AGENT;
+    const maxRefresh = opts.maxRefresh ?? 3;
+    const { proc, ws, dir } = await launchChrome(opts.chromePath, userAgent);
+    let cdp = null;
+    try {
+        cdp = await openTab(ws);
+        const tab = cdp;
+        await tab.send('Network.enable');
+        await tab.send('Page.enable');
+        const result = new Promise((resolve, reject) => {
+            const urlById = new Map();
+            let refreshes = 0;
+            let scanned = false;
+            let done = false;
+            const finish = (err, creds) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                opts.signal?.removeEventListener('abort', onAbort);
+                if (err)
+                    reject(err);
+                else
+                    resolve(creds);
+            };
+            const timer = setTimeout(() => finish(new errors_1.TikTokError('LOGIN_FAILED', 'Timed out waiting for QR scan')), opts.timeoutMs ?? 5 * 60_000);
+            const onAbort = () => finish(new errors_1.TikTokError('LOGIN_ABORTED', 'QR login aborted'));
+            opts.signal?.addEventListener('abort', onAbort);
+            const body = async (requestId) => {
+                const r = await tab.send('Network.getResponseBody', { requestId }).catch(() => null);
+                if (!r)
+                    return null;
+                try {
+                    return JSON.parse(r.base64Encoded ? Buffer.from(r.body, 'base64').toString() : r.body);
+                }
+                catch {
+                    return null;
+                }
+            };
+            /** After `confirmed`: the page redirects and sets session cookies — wait for `sessionid`. */
+            const collectCookies = async () => {
+                for (let i = 0; i < 30 && !done; i++) {
+                    const { cookies } = await tab.send('Network.getAllCookies');
+                    const mine = cookies.filter((c) => c.domain.endsWith('tiktok.com'));
+                    if (mine.some((c) => c.name === 'sessionid' && c.value) && mine.some((c) => c.name === 'ttwid')) {
+                        // Same name on `.tiktok.com` and `www.tiktok.com` → keep the `.tiktok.com` one.
+                        const byName = new Map();
+                        for (const c of mine.sort((a, b) => (a.domain === '.tiktok.com' ? 1 : 0) - (b.domain === '.tiktok.com' ? 1 : 0))) {
+                            byName.set(c.name, { name: c.name, value: c.value });
+                        }
+                        return finish(null, { cookies: [...byName.values()], userAgent });
+                    }
+                    await new Promise((r) => setTimeout(r, 1000));
+                }
+                finish(new errors_1.TikTokError('LOGIN_FAILED', 'Confirmed but no sessionid cookie found'));
+            };
+            tab.on((method, p) => {
+                if (done)
+                    return;
+                if (method === 'Network.responseReceived') {
+                    const res = p.response;
+                    urlById.set(p.requestId, res.url);
+                    return;
+                }
+                if (method !== 'Network.loadingFinished')
+                    return;
+                const url = urlById.get(p.requestId) ?? '';
+                if (url.includes('/passport/web/get_qrcode/')) {
+                    void body(p.requestId).then((j) => {
+                        const qr = j?.data?.qrcode;
+                        if (typeof qr === 'string' && qr) {
+                            opts.onEvent?.({
+                                type: 'qr',
+                                image: `data:image/png;base64,${qr}`,
+                                expiresAt: Number(j?.data?.expire_time ?? 0) * 1000 || Date.now() + 60_000,
+                            });
+                        }
+                    });
+                }
+                else if (url.includes('/passport/web/check_qrconnect/')) {
+                    // The page polls 3 regions in parallel (sg/us/eu) — only the account's region changes status, the rest stay "new".
+                    void body(p.requestId).then((j) => {
+                        const status = String(j?.data?.status ?? '');
+                        if (status === 'scanned' && !scanned) {
+                            scanned = true;
+                            opts.onEvent?.({ type: 'scanned' });
+                        }
+                        else if (status === 'confirmed') {
+                            opts.onEvent?.({ type: 'confirmed' });
+                            void collectCookies();
+                        }
+                        else if (status === 'expired' && !scanned) {
+                            if (refreshes++ >= maxRefresh)
+                                finish(new errors_1.TikTokError('LOGIN_FAILED', 'QR expired without being scanned'));
+                            else
+                                void tab.send('Page.reload');
+                        }
+                    });
+                }
+            });
+        });
+        await tab.send('Page.navigate', { url: `${constants_1.WEB}/login/qrcode` });
+        return await result;
+    }
+    finally {
+        cdp?.close();
+        proc.kill('SIGKILL');
+        await (0, promises_1.rm)(dir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+/** A cookie — same shape as `chrome.cookies.getAll` / CDP `Storage.getCookies` returns (extra fields are fine). */
+export interface CookieInput {
+    name: string;
+    value: string;
+}
+/** What you need to log in again — save it after each login. */
+export 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;
+}
+export 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. */
+export interface ConversationRef {
+    conversationId: string;
+    conversationShortId: string;
+}
+export 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. */
+export 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 ❤️. */
+export interface TikTokReaction {
+    emoji: string;
+    userIds: string[];
+}
+export 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>;
+}
+export interface TikTokConversation extends ConversationRef {
+    participants: string[];
+    /** The other participant in a 1-1 conversation. */
+    peerId: string;
+}
+export 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[];
+}
+export interface TikTokAccount {
+    uid: string;
+    username: string;
+    screenName: string;
+    avatar: string;
+}
+/** Image attachment. */
+export interface ImageInput {
+    data: Buffer;
+    /** Only the extension matters so TikTok knows the format: `photo.jpg`, `bill.png`. */
+    filename: string;
+}
+export interface MessagePage {
+    messages: TikTokMessage[];
+    hasMore: boolean;
+}
+export interface ConversationPage {
+    conversations: TikTokConversation[];
+    /** Latest messages included — handy for building an inbox list. */
+    messages: TikTokMessage[];
+    cursor: string;
+    hasMore: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "tca-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Unofficial TikTok Chat API for JavaScript — read/send TikTok direct messages (text, images, reactions) and listen over websocket using session cookies, no browser needed.",
+  "license": "MIT",
+  "author": "rice2411",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rice2411/tca-js.git"
+  },
+  "homepage": "https://github.com/rice2411/tca-js#readme",
+  "bugs": {
+    "url": "https://github.com/rice2411/tca-js/issues"
+  },
+  "keywords": [
+    "tiktok",
+    "tiktok-api",
+    "tiktok-dm",
+    "tiktok-chat",
+    "direct-message",
+    "unofficial",
+    "chat",
+    "websocket"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.11",
+    "typescript": "5.9.3"
+  }
+}