tokwatchr 0.4.0

package/src/api/client.ts

@@ -0,0 +1,46 @@
+import type { Browser, ImpitOptions } from "impit";
+import { Impit } from "impit";
+import type { CookieJarLike } from "../types.js";
+
+export interface CreateClientOptions {
+	browser?: Browser;
+	proxyUrl?: string | null;
+	timeout?: number;
+	headers?: Record<string, string>;
+	cookieJar?: CookieJarLike | null;
+}
+
+/**
+ * Create an `Impit` HTTP client configured for TikTok.
+ *
+ * Uses browser TLS fingerprint emulation to bypass bot detection.
+ */
+export function createClient(options: CreateClientOptions = {}): Impit {
+	const impitOptions: ImpitOptions = {
+		browser: options.browser ?? "chrome",
+	};
+
+	if (options.proxyUrl) {
+		impitOptions.proxyUrl = options.proxyUrl;
+	}
+
+	if (options.timeout) {
+		impitOptions.timeout = options.timeout;
+	}
+
+	if (options.headers && Object.keys(options.headers).length > 0) {
+		impitOptions.headers = options.headers;
+	}
+
+	if (options.cookieJar) {
+		const jar = options.cookieJar;
+		impitOptions.cookieJar = {
+			setCookie: (cookie: string, url: string) =>
+				Promise.resolve(jar.setCookie(cookie, url)),
+			getCookieString: (url: string) =>
+				Promise.resolve(jar.getCookieString(url)),
+		};
+	}
+
+	return new Impit(impitOptions);
+}

package/src/api/room.ts

@@ -0,0 +1,193 @@
+import type { Impit } from "impit";
+import { RoomResolveError, UserNotFoundError } from "../errors.js";
+
+export interface RoomResolveOptions {
+	impIt?: Impit;
+	signal?: AbortSignal;
+}
+
+/**
+ * TikTok API endpoint patterns for room ID resolution.
+ */
+const TIKTOK_LIVE_URL = "https://www.tiktok.com/@{username}/live";
+const TIKTOK_PROFILE_URL = "https://www.tiktok.com/@{username}";
+const TIKTOK_API_ROOM_URL =
+	"https://www.tiktok.com/api-live/user/room/?aid=1988&uniqueId={username}&sourceType=54";
+
+/**
+ * Check whether a TikTok username exists by hitting the profile page.
+ * Throws UserNotFoundError if the account doesn't exist.
+ */
+async function checkUserExists(
+	username: string,
+	impIt: Impit,
+	signal?: AbortSignal,
+): Promise<void> {
+	const url = TIKTOK_PROFILE_URL.replace("{username}", username);
+	const response = await impIt.fetch(url, {
+		headers: {
+			Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+			"Accept-Language": "en-US,en;q=0.9",
+		},
+		signal,
+	});
+
+	if (response.status === 404) {
+		throw new UserNotFoundError(username);
+	}
+}
+
+/**
+ * Resolve a TikTok username to a live room ID.
+ *
+ * Strategy:
+ * 0. Verify the user exists (profile page check).
+ * 1. Scrape the user's live page HTML for the room ID in SIGI_STATE.
+ * 2. Fall back to the TikTok API.
+ * 3. Throw if neither works.
+ */
+export async function resolveRoomId(
+	username: string,
+	impIt: Impit,
+	options: RoomResolveOptions = {},
+): Promise<string> {
+	const cleanUsername = username.replace(/^@/, "").trim();
+
+	// Strategy 0: Verify the user exists
+	await checkUserExists(cleanUsername, impIt, options.signal);
+
+	// Strategy 1: Scrape the live page
+	const roomId = await tryScrapeRoomId(cleanUsername, impIt, options.signal);
+	if (roomId) {
+		return roomId;
+	}
+
+	// Strategy 2: Use the API
+	const apiRoomId = await tryApiRoomId(cleanUsername, impIt, options.signal);
+	if (apiRoomId) {
+		return apiRoomId;
+	}
+
+	throw new RoomResolveError(cleanUsername);
+}
+
+/**
+ * Try to extract room ID from the TikTok live page HTML.
+ */
+async function tryScrapeRoomId(
+	username: string,
+	impIt: Impit,
+	signal?: AbortSignal,
+): Promise<string | null> {
+	try {
+		const url = TIKTOK_LIVE_URL.replace("{username}", username);
+		const response = await impIt.fetch(url, {
+			headers: {
+				Accept:
+					"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+				"Accept-Language": "en-US,en;q=0.9",
+			},
+			signal,
+		});
+
+		if (!response.ok) {
+			return null;
+		}
+
+		const html = await response.text();
+
+		// Try SIGI_STATE JSON first
+		const roomId = extractRoomIdFromSigiState(html);
+		if (roomId) return roomId;
+
+		// Fallback: regex for "roomId":"<digits>"
+		const roomIdMatch = html.match(/"roomId"\s*:\s*"(\d+)"/);
+		if (roomIdMatch?.[1]) return roomIdMatch[1];
+
+		// Fallback: regex for room_id=<digits>
+		const roomIdParamMatch = html.match(/room_id=(\d+)/);
+		if (roomIdParamMatch?.[1]) return roomIdParamMatch[1];
+
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Try to extract room ID from SIGI_STATE embedded JSON.
+ */
+function extractRoomIdFromSigiState(html: string): string | null {
+	try {
+		const match = html.match(
+			/<script[^>]*id=["']SIGI_STATE["'][^>]*type=["']application\/json["'][^>]*>([\s\S]*?)<\/script>/i,
+		);
+		if (!match) return null;
+
+		const sigiState = JSON.parse(match[1] as string);
+
+		// Traverse potential paths
+		const liveRoom = sigiState?.LiveRoom?.liveRoomInfo;
+		if (liveRoom?.roomId) {
+			return String(liveRoom.roomId);
+		}
+
+		// Alternate path
+		const liveRoom2 = sigiState?.LiveRoom?.liveRoomInfo?.user?.roomId;
+		if (liveRoom2) {
+			return String(liveRoom2);
+		}
+
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Try to resolve room ID via the TikTok API.
+ */
+async function tryApiRoomId(
+	username: string,
+	impIt: Impit,
+	signal?: AbortSignal,
+): Promise<string | null> {
+	try {
+		const url = TIKTOK_API_ROOM_URL.replace(
+			"{username}",
+			encodeURIComponent(username),
+		);
+		const response = await impIt.fetch(url, {
+			headers: {
+				Accept: "application/json, text/plain, */*",
+				Referer: `https://www.tiktok.com/@${username}`,
+			},
+			signal,
+		});
+
+		if (!response.ok) {
+			return null;
+		}
+
+		const data = (await response.json()) as Record<string, unknown>;
+		const dataObj = data.data as Record<string, unknown> | undefined;
+
+		if (!dataObj) return null;
+
+		// Check status - 2 means live
+		const liveRoom = dataObj.liveRoom as Record<string, unknown> | undefined;
+		if (liveRoom?.status !== 2) return null;
+
+		const user = dataObj.user as Record<string, unknown> | undefined;
+		if (!user) return null;
+
+		const roomId = user.roomId;
+		if (roomId) {
+			return String(roomId);
+		}
+
+		return null;
+	} catch {
+		return null;
+	}
+}

package/src/api/stream.ts

@@ -0,0 +1,76 @@
+import type { Impit } from "impit";
+import { StreamFetchError } from "../errors.js";
+import type { StreamInfo, StreamQualityKey } from "../types.js";
+import { parseQualities, selectQuality } from "../utils/quality.js";
+
+export interface StreamInfoOptions {
+	quality?: "best" | "worst" | StreamQualityKey;
+	signal?: AbortSignal;
+}
+
+/**
+ * Fetch stream info for a given room ID.
+ *
+ * Calls the TikTok webcast room/info API and parses the response
+ * to extract stream URLs and quality options.
+ */
+export async function fetchStreamInfo(
+	roomId: string,
+	username: string,
+	impIt: Impit,
+	options: StreamInfoOptions = {},
+): Promise<StreamInfo> {
+	const url = `https://webcast.tiktok.com/webcast/room/info/?aid=1988&room_id=${encodeURIComponent(roomId)}`;
+
+	const response = await impIt.fetch(url, {
+		headers: {
+			Accept: "application/json, text/plain, */*",
+			Referer: `https://www.tiktok.com/@${username}/live`,
+		},
+		signal: options.signal,
+	});
+
+	if (!response.ok) {
+		throw new StreamFetchError(
+			roomId,
+			`HTTP ${response.status}: ${response.statusText}`,
+		);
+	}
+
+	const json = (await response.json()) as Record<string, unknown>;
+	const data = json.data as Record<string, unknown> | undefined;
+
+	if (!data) {
+		throw new StreamFetchError(roomId, "No data in response");
+	}
+
+	const status = data.status;
+	if (status !== 2) {
+		throw new StreamFetchError(roomId, `Room is not live (status: ${status})`);
+	}
+
+	const qualities = parseQualities(data);
+	if (qualities.length === 0) {
+		throw new StreamFetchError(roomId, "No stream qualities found");
+	}
+
+	const selectedQuality = selectQuality(qualities, options.quality ?? "best");
+
+	const title = typeof data.title === "string" ? data.title : "";
+	const viewerCount =
+		typeof (data.stats as Record<string, unknown> | undefined)?.viewer_count ===
+		"number"
+			? ((data.stats as Record<string, unknown>).viewer_count as number)
+			: 0;
+
+	return {
+		roomId,
+		username,
+		title,
+		qualities,
+		selectedQuality,
+		streamUrl: selectedQuality.flv,
+		viewerCount,
+		startedAt: new Date(),
+	};
+}

package/src/download/ffmpeg.ts

@@ -0,0 +1,303 @@
+import { spawn } from "node:child_process";
+import { FfmpegError } from "../errors.js";
+import type { DownloadStats, StreamQualityKey } from "../types.js";
+
+export interface FfmpegDownloadOptions {
+	ffmpegPath: string;
+	url: string;
+	outputPath: string;
+	quality: StreamQualityKey;
+	args?: string[];
+	bitrate?: string | null;
+	signal?: AbortSignal;
+	onProgress?: (stats: DownloadStats) => void;
+	maxDuration?: number;
+	/**
+	 * Startup timeout in ms. If ffmpeg produces no stderr output within
+	 * this window, it is killed and the promise rejects. Prevents
+	 * indefinite hangs on bad/ stalled stream URLs.
+	 * @default 30_000
+	 */
+	timeout?: number;
+}
+
+/**
+ * Parse ffmpeg stderr for duration and time progress.
+ *
+ * ffmpeg outputs lines like:
+ *   frame=  123 fps= 30 q=28.0 size=    1024kB time=00:01:23.45 ...
+ */
+function parseFfmpegProgress(
+	line: string,
+): { duration?: number; sizeBytes?: number } | null {
+	const result: { duration?: number; sizeBytes?: number } = {};
+
+	// Parse time=HH:MM:SS.MS
+	const timeMatch = line.match(/time=(\d+):(\d+):(\d+)\.(\d+)/);
+	if (timeMatch) {
+		const hours = Number(timeMatch[1]);
+		const minutes = Number(timeMatch[2]);
+		const seconds = Number(timeMatch[3]);
+		result.duration = hours * 3600 + minutes * 60 + seconds;
+	}
+
+	// Parse size=   1024kB
+	const sizeMatch = line.match(/size=\s*(\d+)(\w+)B/);
+	if (sizeMatch && sizeMatch.length >= 3) {
+		const value = Number(sizeMatch[1]);
+		// biome-ignore lint/style/noNonNullAssertion: length >= 3 guarantees index 2
+		const unit = sizeMatch[2]!;
+		if (unit === "k" || unit === "K") {
+			result.sizeBytes = value * 1024;
+		} else if (unit === "m" || unit === "M") {
+			result.sizeBytes = value * 1024 * 1024;
+		} else {
+			result.sizeBytes = value;
+		}
+	}
+
+	return result.sizeBytes !== undefined || result.duration !== undefined
+		? result
+		: null;
+}
+
+/**
+ * Download a livestream via ffmpeg.
+ *
+ * Spawns ffmpeg as a subprocess, pipes the stream URL as input,
+ * and writes the transcoded/remuxed output to the specified path.
+ *
+ * Advantages over raw HTTP:
+ * - Proper container format (mp4/mkv)
+ * - Stream copy (fast) or re-encode
+ * - Better handling of stream interruptions
+ */
+export async function downloadWithFfmpeg(
+	options: FfmpegDownloadOptions,
+): Promise<{
+	sizeBytes: number;
+	duration: number;
+	format: "mp4" | "mkv";
+}> {
+	const {
+		ffmpegPath,
+		url,
+		outputPath,
+		quality,
+		args: extraArgs,
+		bitrate,
+		signal,
+		onProgress,
+		maxDuration,
+		timeout = 30_000,
+	} = options;
+
+	const ffmpegArgs: string[] = [
+		"-y", // overwrite output
+		"-i",
+		url, // input URL
+	];
+
+	if (maxDuration && maxDuration > 0 && maxDuration < Infinity) {
+		ffmpegArgs.push("-t", String(maxDuration));
+	}
+
+	if (bitrate) {
+		ffmpegArgs.push("-c:v", "libx264", "-b:v", bitrate, "-c:a", "copy");
+	} else if (extraArgs && extraArgs.length > 0) {
+		ffmpegArgs.push(...extraArgs);
+	} else {
+		ffmpegArgs.push("-c", "copy");
+	}
+
+	ffmpegArgs.push(outputPath);
+
+	return new Promise((resolve, reject) => {
+		const proc = spawn(ffmpegPath, ffmpegArgs, {
+			stdio: ["ignore", "pipe", "pipe"],
+			signal,
+		});
+
+		let stderrBuffer = "";
+		let sizeBytes = 0;
+		let duration = 0;
+
+		const abortHandler = () => {
+			// SIGTERM tells ffmpeg to flush its output (moov atom, etc.)
+			// and exit cleanly. This produces a playable file even when
+			// stopped mid-recording.
+			proc.kill("SIGTERM");
+			// Safety net: if ffmpeg doesn't respond, force-kill after 15s.
+			// The close handler will still fire and resolve with partial data.
+			setTimeout(() => {
+				if (proc.exitCode === null) {
+					proc.kill("SIGKILL");
+				}
+			}, 15_000);
+		};
+
+		let aborted = false;
+		const onAbort = () => {
+			aborted = true;
+			abortHandler();
+		};
+
+		signal?.addEventListener("abort", onAbort, { once: true });
+
+		// Startup timeout — if ffmpeg produces no stderr output within
+		// `timeout` ms, it likely stalled on a bad URL. Kill it so the
+		// caller doesn't hang indefinitely.
+		let firstDataTimer: ReturnType<typeof setTimeout> | null = setTimeout(
+			() => {
+				firstDataTimer = null;
+				signal?.removeEventListener("abort", onAbort);
+				proc.kill("SIGTERM");
+				reject(
+					new FfmpegError(
+						`ffmpeg produced no output within ${timeout}ms — check the stream URL`,
+					),
+				);
+			},
+			timeout,
+		);
+
+		// Parse stderr for progress
+		proc.stderr?.on("data", (chunk: Buffer | string) => {
+			// Clear first-data timer on first output — ffmpeg is working
+			if (firstDataTimer) {
+				clearTimeout(firstDataTimer);
+				firstDataTimer = null;
+			}
+			const text = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+			stderrBuffer += text;
+
+			const lines = text.split("\n");
+			for (const line of lines) {
+				const parsed = parseFfmpegProgress(line);
+				if (parsed) {
+					if (parsed.duration !== undefined) {
+						duration = parsed.duration;
+					}
+					if (parsed.sizeBytes !== undefined) {
+						sizeBytes = parsed.sizeBytes;
+					}
+
+					onProgress?.({
+						downloadedBytes: sizeBytes,
+						downloadedMB: sizeBytes / (1024 * 1024),
+						duration,
+						speed: duration > 0 ? sizeBytes / duration : 0,
+						speedMBps: duration > 0 ? sizeBytes / duration / (1024 * 1024) : 0,
+						quality,
+						state: "recording",
+					});
+				}
+			}
+		});
+
+		proc.on("error", (err) => {
+			if (firstDataTimer) {
+				clearTimeout(firstDataTimer);
+				firstDataTimer = null;
+			}
+			signal?.removeEventListener("abort", onAbort);
+			reject(new FfmpegError(err.message));
+		});
+
+		proc.on("close", (code) => {
+			if (firstDataTimer) {
+				clearTimeout(firstDataTimer);
+				firstDataTimer = null;
+			}
+			signal?.removeEventListener("abort", onAbort);
+
+			// When the user aborted, resolve with whatever we got.
+			// ffmpeg receives SIGTERM first, which tells it to flush
+			// its output and exit cleanly, producing a playable file.
+			if (aborted) {
+				resolve({
+					sizeBytes,
+					duration,
+					format: outputPath.endsWith(".mkv") ? "mkv" : "mp4",
+				});
+				return;
+			}
+
+			if (code === 0) {
+				// Clean exit — check we actually got data
+				if (sizeBytes > 0) {
+					resolve({
+						sizeBytes,
+						duration,
+						format: outputPath.endsWith(".mkv") ? "mkv" : "mp4",
+					});
+				} else {
+					reject(
+						new FfmpegError(
+							extractFfmpegError(stderrBuffer) || "Stream was empty",
+							code,
+						),
+					);
+				}
+			} else if (code === null) {
+				// Process killed by signal (SIGTERM, SIGKILL, etc.)
+				if (sizeBytes > 0) {
+					resolve({
+						sizeBytes,
+						duration,
+						format: outputPath.endsWith(".mkv") ? "mkv" : "mp4",
+					});
+				} else {
+					reject(
+						new FfmpegError(
+							"Process was killed before any data was received",
+							code,
+						),
+					);
+				}
+			} else if (code === 1 || code === 255) {
+				// ffmpeg exit codes for interruption / end-of-stream
+				if (sizeBytes > 0) {
+					resolve({
+						sizeBytes,
+						duration,
+						format: outputPath.endsWith(".mkv") ? "mkv" : "mp4",
+					});
+				} else {
+					const errorMsg = extractFfmpegError(stderrBuffer);
+					reject(
+						new FfmpegError(
+							errorMsg || `FFmpeg exited with code ${code} and no data`,
+							code,
+						),
+					);
+				}
+			} else {
+				// Extract error from stderr
+				const errorMsg = extractFfmpegError(stderrBuffer);
+				reject(new FfmpegError(errorMsg, code));
+			}
+		});
+	});
+}
+
+/**
+ * Extract a meaningful error message from ffmpeg stderr output.
+ */
+function extractFfmpegError(stderr: string): string {
+	const lines = stderr.split("\n").filter((l) => l.trim().length > 0);
+	const errorLines = lines.filter(
+		(l) =>
+			l.toLowerCase().includes("error") ||
+			l.toLowerCase().includes("invalid") ||
+			l.toLowerCase().includes("cannot"),
+	);
+
+	if (errorLines.length > 0) {
+		// biome-ignore lint/style/noNonNullAssertion: length > 0 guarantees index 0
+		return errorLines[0]!.trim();
+	}
+
+	// Return last meaningful line
+	return lines[lines.length - 1]?.trim() ?? "Unknown ffmpeg error";
+}