tca-js 0.0.0-stage → 0.3.1

package/dist/media.d.ts

@@ -0,0 +1,27 @@
+import type { Context } from './context';
+import type { ImageInput, TikTokImage } from './types';
+/** Uploaded image, encrypted by the store — enough to send an image message. */
+export interface UploadedImage {
+    uri: string;
+    secretKey: string;
+    width: number;
+    height: number;
+    size: number;
+    filename: string;
+}
+export declare class MediaClient {
+    private readonly ctx;
+    private cred;
+    constructor(ctx: Context);
+    /** `UploadConfig` returns two credential sets: type 1 = ImageX (images), type 2 = VOD (video). Use type 1. */
+    private credential;
+    /** Call ImageX signed with AWS SigV4 (region cn-north-1, service imagex). */
+    private imagex;
+    /**
+     * Upload an image to the private message store: Apply → POST file → Commit (the store encrypts with AES-GCM
+     * and returns the key). Image dimensions come from the Commit result — no need to decode the image.
+     */
+    upload(image: ImageInput): Promise<UploadedImage>;
+    /** Download and decrypt a message image. Layout: 12-byte IV ‖ ciphertext ‖ 16-byte tag. */
+    download(image: TikTokImage, which?: 'origin' | 'thumb'): Promise<Buffer>;
+}

package/dist/media.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaClient = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_zlib_1 = require("node:zlib");
+const constants_1 = require("./constants");
+const errors_1 = require("./errors");
+const sha256 = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
+const hmac = (k, s) => (0, node_crypto_1.createHmac)('sha256', k).update(s).digest();
+const rfc3986 = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+class MediaClient {
+    ctx;
+    cred = null;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** `UploadConfig` returns two credential sets: type 1 = ImageX (images), type 2 = VOD (video). Use type 1. */
+    async credential() {
+        if (this.cred && this.cred.expiresAt - Date.now() > 60_000)
+            return this.cred;
+        const body = await this.ctx.im('/v1/media/upload_config', constants_1.Cmd.UploadConfig, Buffer.alloc(0));
+        const c = body.msgs(1).find((m) => m.num(1) === 1);
+        if (!c)
+            throw new errors_1.TikTokError('UPLOAD_FAILED', 'upload_config has no ImageX credentials');
+        this.cred = {
+            serviceId: c.str(2),
+            host: c.str(3),
+            expiresAt: c.num(4),
+            accessKeyId: c.str(6),
+            sessionToken: c.str(7),
+            secretAccessKey: c.str(8),
+        };
+        return this.cred;
+    }
+    /** Call ImageX signed with AWS SigV4 (region cn-north-1, service imagex). */
+    async imagex(method, params, body) {
+        const c = await this.credential();
+        const amzDate = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+/, '');
+        const date = amzDate.slice(0, 8);
+        const query = Object.keys(params)
+            .sort()
+            .map((k) => `${rfc3986(k)}=${rfc3986(params[k])}`)
+            .join('&');
+        const headers = { 'x-amz-date': amzDate, 'x-amz-security-token': c.sessionToken };
+        if (body !== undefined)
+            headers['x-amz-content-sha256'] = sha256(body);
+        const signed = Object.keys(headers).sort();
+        const canonical = [
+            method,
+            '/',
+            query,
+            signed.map((k) => `${k}:${headers[k]}\n`).join(''),
+            signed.join(';'),
+            body !== undefined ? headers['x-amz-content-sha256'] : sha256(''),
+        ].join('\n');
+        const scope = `${date}/${constants_1.IMAGEX_REGION}/${constants_1.IMAGEX_SERVICE}/aws4_request`;
+        const toSign = ['AWS4-HMAC-SHA256', amzDate, scope, sha256(canonical)].join('\n');
+        let k = hmac(`AWS4${c.secretAccessKey}`, date);
+        k = hmac(k, constants_1.IMAGEX_REGION);
+        k = hmac(k, constants_1.IMAGEX_SERVICE);
+        k = hmac(k, 'aws4_request');
+        const signature = (0, node_crypto_1.createHmac)('sha256', k).update(toSign).digest('hex');
+        const res = await fetch(`https://${c.host}/?${query}`, {
+            method,
+            headers: {
+                ...headers,
+                Authorization: `AWS4-HMAC-SHA256 Credential=${c.accessKeyId}/${scope}, SignedHeaders=${signed.join(';')}, Signature=${signature}`,
+                ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+            },
+            body,
+            signal: AbortSignal.timeout(this.ctx.options.timeoutMs ?? 20_000),
+        });
+        const json = (await res.json().catch(() => null));
+        const err = json?.ResponseMetadata?.Error;
+        if (!res.ok || !json || err) {
+            throw new errors_1.TikTokError('UPLOAD_FAILED', `imagex ${params.Action}: ${err?.Message ?? `HTTP ${res.status}`}`, err?.CodeN ?? res.status);
+        }
+        return json;
+    }
+    /**
+     * Upload an image to the private message store: Apply → POST file → Commit (the store encrypts with AES-GCM
+     * and returns the key). Image dimensions come from the Commit result — no need to decode the image.
+     */
+    async upload(image) {
+        const c = await this.credential();
+        const ext = (/\.([a-z0-9]{2,5})$/i.exec(image.filename)?.[1] ?? 'jpg').toLowerCase();
+        const apply = await this.imagex('GET', {
+            Action: 'ApplyImageUpload',
+            Version: constants_1.IMAGEX_VERSION,
+            ServiceId: c.serviceId,
+            FileSize: String(image.data.length),
+            FileExtension: `.${ext}`,
+            s: (0, node_crypto_1.randomBytes)(6).toString('hex').slice(0, 10),
+        });
+        const addr = apply.Result.UploadAddress;
+        const store = addr.StoreInfos[0];
+        const host = addr.UploadHosts[0];
+        if (!store || !host)
+            throw new errors_1.TikTokError('UPLOAD_FAILED', 'ApplyImageUpload returned no upload target');
+        const up = await fetch(`https://${host}/upload/v1/${store.StoreUri}`, {
+            method: 'POST',
+            headers: {
+                Authorization: store.Auth,
+                'Content-CRC32': ((0, node_zlib_1.crc32)(image.data) >>> 0).toString(16).padStart(8, '0'),
+                // Without this header the store returns 4004 Not Found.
+                'X-Storage-U': this.ctx.ownId,
+                'Content-Type': 'application/octet-stream',
+                'Content-Disposition': 'attachment; filename="undefined"',
+            },
+            body: new Uint8Array(image.data),
+            signal: AbortSignal.timeout(this.ctx.options.timeoutMs ?? 60_000),
+        });
+        const upJson = (await up.json().catch(() => null));
+        if (!up.ok || upJson?.code !== 2000) {
+            throw new errors_1.TikTokError('UPLOAD_FAILED', `upload: ${upJson?.message ?? `HTTP ${up.status}`}`, upJson?.code ?? up.status);
+        }
+        const commit = await this.imagex('POST', { Action: 'CommitImageUpload', Version: constants_1.IMAGEX_VERSION, ServiceId: c.serviceId }, JSON.stringify({ SessionKey: addr.SessionKey, Functions: [{ name: 'Encryption', input: { Config: { copies: 'cipher_v2' } } }] }));
+        const enc = commit.Result.Results?.[0]?.Encryption;
+        const plugin = commit.Result.PluginResult?.[0];
+        if (!enc?.Uri || !enc.SecretKey)
+            throw new errors_1.TikTokError('UPLOAD_FAILED', 'CommitImageUpload returned no encrypted result');
+        return {
+            uri: enc.Uri,
+            secretKey: enc.SecretKey,
+            width: plugin?.ImageWidth ?? Number(enc.Extra?.img_width ?? 0),
+            height: plugin?.ImageHeight ?? Number(enc.Extra?.img_height ?? 0),
+            size: plugin?.ImageSize ?? image.data.length,
+            filename: image.filename,
+        };
+    }
+    /** Download and decrypt a message image. Layout: 12-byte IV ‖ ciphertext ‖ 16-byte tag. */
+    async download(image, which = 'origin') {
+        const url = which === 'thumb' && image.thumbUrl ? image.thumbUrl : image.url;
+        if (!url)
+            throw new errors_1.TikTokError('DOWNLOAD_FAILED', 'Image has no URL');
+        const res = await this.ctx.fetch(url);
+        if (!res.ok)
+            throw new errors_1.TikTokError('DOWNLOAD_FAILED', `Image download: HTTP ${res.status}`, res.status);
+        const enc = Buffer.from(await res.arrayBuffer());
+        if (!image.decryptKey)
+            return enc;
+        try {
+            const d = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', Buffer.from(image.decryptKey, 'hex'), enc.subarray(0, 12));
+            d.setAuthTag(enc.subarray(enc.length - 16));
+            return Buffer.concat([d.update(enc.subarray(12, enc.length - 16)), d.final()]);
+        }
+        catch (err) {
+            throw new errors_1.TikTokError('DOWNLOAD_FAILED', `Image decryption: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+exports.MediaClient = MediaClient;

package/dist/message.d.ts

@@ -0,0 +1,6 @@
+import { Msg } from './proto';
+import type { TikTokConversation, TikTokMessage } from './types';
+/** `MessageBody` → `TikTokMessage`. */
+export declare function parseMessage(m: Msg, ownId: string): TikTokMessage;
+/** `ConversationInfo` (field 2 of get_by_user_init): {1 id, 2 shortId, 3 type, 6 {1 {1 uid}}…}. */
+export declare function parseConversation(m: Msg, ownId: string): TikTokConversation;

package/dist/message.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMessage = parseMessage;
+exports.parseConversation = parseConversation;
+const constants_1 = require("./constants");
+function parseJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+}
+/** Image in `attachments` (field 20 → 4): 1 = original, 2 = thumbnail; each {1 uri, 2 url…, 5 {w,h}, 6 key}. */
+function parseImage(m) {
+    const media = m.msg(constants_1.MsgF.attachments)?.msg(4);
+    const origin = media?.msg(1);
+    if (!media || !origin)
+        return null;
+    const size = origin.msg(5);
+    return {
+        uri: origin.str(1),
+        url: origin.strs(2)[0] ?? '',
+        thumbUrl: media.msg(2)?.strs(2)[0] ?? '',
+        width: size?.num(1) ?? 0,
+        height: size?.num(2) ?? 0,
+        decryptKey: origin.str(6),
+    };
+}
+/**
+ * Sticker (field 20 → 7): `{1 {1 uri, 2 url, 5 {w,h}}, 2 hint, 200 {1 {2 map a:sticker_id, a:sticker_type…}}}`.
+ * Links point to the public sticker CDN (`…-dm-sticker-sign-…`) — not encrypted, no cookies needed.
+ */
+function parseSticker(m) {
+    const st = m.msg(constants_1.MsgF.attachments)?.msg(7);
+    const img = st?.msg(1);
+    if (!st || !img)
+        return null;
+    const size = img.msg(5);
+    const ext = st.msg(200)?.msg(1)?.map(2) ?? {};
+    return {
+        stickerId: ext['a:sticker_id'] ?? '',
+        stickerType: Number(ext['a:sticker_type'] ?? 0),
+        url: img.str(2),
+        width: size?.num(1) ?? 0,
+        height: size?.num(2) ?? 0,
+    };
+}
+/**
+ * Reaction (field 15, `property_list`): each entry `{1 key, 2 {1 PropertyItem[]}}`, key `e:<emoji>`,
+ * `PropertyItem {1 uid, 3 sec, 4 idempotent_id, 6 µs}`. The mobile app writes ❤️ as both `e:❤️` and `e:love` → merged.
+ */
+function parseReactions(m) {
+    const byEmoji = new Map();
+    for (const p of m.msgs(constants_1.MsgF.propertyList)) {
+        const key = p.str(1);
+        if (!key.startsWith(constants_1.REACTION_PREFIX))
+            continue;
+        const emoji = key === constants_1.REACTION_LOVE_KEY ? constants_1.REACTION_HEART : key.slice(constants_1.REACTION_PREFIX.length);
+        const uids = byEmoji.get(emoji) ?? new Set();
+        for (const item of p.msg(2)?.msgs(1) ?? [])
+            uids.add(item.id(1));
+        if (uids.size)
+            byEmoji.set(emoji, uids);
+    }
+    return [...byEmoji].map(([emoji, uids]) => ({ emoji, userIds: [...uids] }));
+}
+const KIND = {
+    [constants_1.MessageType.Text]: 'text',
+    [constants_1.MessageType.PrivateImage]: 'image',
+    [constants_1.MessageType.Sticker]: 'sticker',
+    [constants_1.MessageType.ShareVideo]: 'video',
+    [constants_1.MessageType.System]: 'system',
+    [constants_1.MessageType.Command]: 'command',
+};
+/** `MessageBody` → `TikTokMessage`. */
+function parseMessage(m, ownId) {
+    const type = m.num(constants_1.MsgF.type);
+    const content = parseJson(m.str(constants_1.MsgF.content));
+    const ext = m.map(constants_1.MsgF.ext);
+    const senderId = m.id(constants_1.MsgF.sender);
+    const text = type === constants_1.MessageType.Text && content && typeof content === 'object' && 'text' in content
+        ? String(content.text ?? '')
+        : '';
+    return {
+        conversationId: m.str(constants_1.MsgF.conversationId),
+        conversationShortId: m.id(constants_1.MsgF.conversationShortId),
+        serverMessageId: m.id(constants_1.MsgF.serverMessageId),
+        index: m.id(constants_1.MsgF.indexInConversation),
+        type,
+        kind: KIND[type] ?? 'other',
+        senderId,
+        isSelf: senderId === ownId,
+        text,
+        image: type === constants_1.MessageType.PrivateImage ? parseImage(m) : null,
+        sticker: type === constants_1.MessageType.Sticker ? parseSticker(m) : null,
+        reactions: parseReactions(m),
+        content,
+        createdAt: m.num(constants_1.MsgF.createTime),
+        clientMessageId: ext['s:client_message_id'] ?? '',
+        ext,
+    };
+}
+/** `ConversationInfo` (field 2 of get_by_user_init): {1 id, 2 shortId, 3 type, 6 {1 {1 uid}}…}. */
+function parseConversation(m, ownId) {
+    const participants = (m.msg(6)?.msgs(1) ?? []).map((p) => p.id(1));
+    return {
+        conversationId: m.str(1),
+        conversationShortId: m.id(2),
+        participants,
+        peerId: participants.find((p) => p !== ownId) ?? '',
+    };
+}

package/dist/proto.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export interface Field {
+    n: number;
+    wire: number;
+    int: bigint;
+    bytes: Buffer;
+}
+/** Split a message into a list of fields. `null` if the bytes are not valid protobuf. */
+export declare function decodeFields(b: Buffer): Field[] | null;
+/** Decoded message — read by field number. */
+export 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>;
+}
+/** Build a message in call order. */
+export declare class Writer {
+    private readonly parts;
+    int(n: number, v: bigint | number | string): this;
+    bytes(n: number, v: Buffer | string): this;
+    msg(n: number, w: Writer): this;
+    /** `map<string,string>` in the object's key order. */
+    map(n: number, obj: Record<string, string>): this;
+    finish(): Buffer;
+}

package/dist/proto.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Writer = exports.Msg = void 0;
+exports.decodeFields = decodeFields;
+function readVarint(b, i) {
+    let x = 0n;
+    let shift = 0n;
+    let c;
+    do {
+        if (i >= b.length)
+            throw new Error('varint runs past end of buffer');
+        c = b[i++];
+        x |= BigInt(c & 127) << shift;
+        shift += 7n;
+    } while (c & 128);
+    return [x, i];
+}
+/** Split a message into a list of fields. `null` if the bytes are not valid protobuf. */
+function decodeFields(b) {
+    const out = [];
+    let i = 0;
+    try {
+        while (i < b.length) {
+            const [key, j] = readVarint(b, i);
+            i = j;
+            const wire = Number(key & 7n);
+            const n = Number(key >> 3n);
+            if (n === 0)
+                return null;
+            if (wire === 0) {
+                const [v, k] = readVarint(b, i);
+                out.push({ n, wire, int: v, bytes: Buffer.alloc(0) });
+                i = k;
+            }
+            else if (wire === 2) {
+                const [len, k] = readVarint(b, i);
+                const end = k + Number(len);
+                if (end > b.length)
+                    return null;
+                out.push({ n, wire, int: 0n, bytes: b.subarray(k, end) });
+                i = end;
+            }
+            else if (wire === 1 || wire === 5) {
+                const size = wire === 1 ? 8 : 4;
+                if (i + size > b.length)
+                    return null;
+                out.push({ n, wire, int: 0n, bytes: b.subarray(i, i + size) });
+                i += size;
+            }
+            else {
+                return null;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return out;
+}
+/** Decoded message — read by field number. */
+class Msg {
+    fields;
+    constructor(fields) {
+        this.fields = fields;
+    }
+    static parse(b) {
+        const f = decodeFields(b);
+        if (!f)
+            throw new Error('Failed to decode protobuf');
+        return new Msg(f);
+    }
+    static tryParse(b) {
+        if (!b)
+            return null;
+        const f = decodeFields(b);
+        return f ? new Msg(f) : null;
+    }
+    has(n) {
+        return this.fields.some((f) => f.n === n);
+    }
+    int(n) {
+        return this.fields.find((f) => f.n === n)?.int ?? 0n;
+    }
+    num(n) {
+        return Number(this.int(n));
+    }
+    /** 64-bit integer as a string — uids / message IDs exceed `Number.MAX_SAFE_INTEGER`. */
+    id(n) {
+        return this.int(n).toString();
+    }
+    bytes(n) {
+        return this.fields.find((f) => f.n === n)?.bytes ?? Buffer.alloc(0);
+    }
+    str(n) {
+        return this.bytes(n).toString('utf8');
+    }
+    strs(n) {
+        return this.fields.filter((f) => f.n === n).map((f) => f.bytes.toString('utf8'));
+    }
+    msg(n) {
+        return Msg.tryParse(this.fields.find((f) => f.n === n)?.bytes);
+    }
+    msgs(n) {
+        return this.fields
+            .filter((f) => f.n === n)
+            .map((f) => Msg.tryParse(f.bytes))
+            .filter((m) => m !== null);
+    }
+    /** `map<string,string>` — each entry is a message `{1: key, 2: value}`. */
+    map(n) {
+        const out = {};
+        for (const m of this.msgs(n))
+            out[m.str(1)] = m.str(2);
+        return out;
+    }
+}
+exports.Msg = Msg;
+function varint(x) {
+    let v = BigInt(x);
+    if (v < 0n)
+        v = BigInt.asUintN(64, v);
+    const out = [];
+    do {
+        const c = Number(v & 127n);
+        v >>= 7n;
+        out.push(v ? c | 128 : c);
+    } while (v);
+    return Buffer.from(out);
+}
+const key = (n, wire) => varint((BigInt(n) << 3n) | BigInt(wire));
+/** Build a message in call order. */
+class Writer {
+    parts = [];
+    int(n, v) {
+        this.parts.push(key(n, 0), varint(typeof v === 'string' ? BigInt(v) : v));
+        return this;
+    }
+    bytes(n, v) {
+        const b = typeof v === 'string' ? Buffer.from(v, 'utf8') : v;
+        this.parts.push(key(n, 2), varint(b.length), b);
+        return this;
+    }
+    msg(n, w) {
+        return this.bytes(n, w.finish());
+    }
+    /** `map<string,string>` in the object's key order. */
+    map(n, obj) {
+        for (const [k, v] of Object.entries(obj))
+            this.msg(n, new Writer().bytes(1, k).bytes(2, v));
+        return this;
+    }
+    finish() {
+        return Buffer.concat(this.parts);
+    }
+}
+exports.Writer = Writer;

package/dist/qr-login.d.ts

@@ -0,0 +1,41 @@
+import type { Credentials } from './types';
+/**
+ * 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.
+ */
+export 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';
+};
+export interface QrLoginOptions {
+    /** Path to Chrome / Chromium (e.g. `/usr/bin/chromium-browser`). */
+    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.
+ */
+export declare function loginQR(opts: QrLoginOptions): Promise<Credentials>;