tokwatchr 0.4.4 → 0.5.0

package/dist/index.d.mts

@@ -88,7 +88,17 @@ interface CookieJarLike {
   setCookie(raw: string, url: string): Promise<void>;
   getCookieString(url: string): Promise<string>;
 }
+interface WaitingInfo {
+  /** The username being waited on. */
+  username: string;
+  /** Which phase we're waiting in: "room" = looking for a room, "stream" = stream not active. */
+  phase: "room" | "stream";
+  /** Seconds elapsed since this phase started. */
+  elapsed: number;
+}
 interface TikTokLiveDownloaderEvents {
+  /** Emitted periodically while waiting for a room or stream to become active. */
+  waiting: [info: WaitingInfo];
   /** Emitted when a live stream is detected and we're about to start recording. */
   start: [info: StreamInfo];
   /** Emitted periodically (every ~1s) during recording with current stats. */
@@ -330,4 +340,4 @@ declare function renderFilename(template: string, values: {
   part?: number;
 }): string;
 //#endregion
-export { AbortError, type CookieJarLike, type CreateClientOptions, DownloadFailedError, type DownloadFunctionOptions, type DownloadResult, type DownloadStats, type DownloaderState, FfmpegError, type OutputFormat, type QualityOption, RoomResolveError, type RoomResolveOptions, StreamFetchError, type StreamInfo, type StreamInfoOptions, type StreamQualityKey, TikTokLiveDownloader, type TikTokLiveDownloaderEvents, type TikTokLiveDownloaderOptions, TikTokLiveError, UserNotFoundError, UserOfflineError, buildQualityOption, createClient, download, fetchStreamInfo, parseQualities, renderFilename, resolveRoomId, selectQuality };
+export { AbortError, type CookieJarLike, type CreateClientOptions, DownloadFailedError, type DownloadFunctionOptions, type DownloadResult, type DownloadStats, type DownloaderState, FfmpegError, type OutputFormat, type QualityOption, RoomResolveError, type RoomResolveOptions, StreamFetchError, type StreamInfo, type StreamInfoOptions, type StreamQualityKey, TikTokLiveDownloader, type TikTokLiveDownloaderEvents, type TikTokLiveDownloaderOptions, TikTokLiveError, UserNotFoundError, UserOfflineError, type WaitingInfo, buildQualityOption, createClient, download, fetchStreamInfo, parseQualities, renderFilename, resolveRoomId, selectQuality };

package/dist/index.mjs

@@ -808,6 +808,11 @@ var TikTokLiveDownloader = class {
 			this.emit("complete", finalResults);
 			return finalResults[finalResults.length - 1];
 		} catch (err) {
+			if (err instanceof StreamFetchError) this.emit("waiting", {
+				username: this.username,
+				phase: "stream",
+				elapsed: 0
+			});
 			if (pendingRemuxes.length > 0) await Promise.allSettled(pendingRemuxes);
 			this.setState("done");
 			const error = err instanceof Error ? err : new Error(String(err));
@@ -835,10 +840,16 @@ var TikTokLiveDownloader = class {
 	async resolveRoomIdWithRetry() {
 		const interval = this.options.checkInterval;
 		const maxInterval = Math.max(interval, 18e4);
+		const waitStart = Date.now();
 		while (true) {
 			this.abortController.signal?.throwIfAborted();
 			const roomId = await this.resolveRoomIdOnce();
 			if (roomId) return roomId;
+			this.emit("waiting", {
+				username: this.username,
+				phase: "room",
+				elapsed: (Date.now() - waitStart) / 1e3
+			});
 			await sleep(maxInterval);
 		}
 	}
@@ -859,12 +870,18 @@ var TikTokLiveDownloader = class {
 	async pollStreamInfo(roomId) {
 		const interval = this.options.checkInterval;
 		const maxInterval = Math.max(interval, 18e4);
+		const waitStart = Date.now();
 		while (true) {
 			this.abortController.signal?.throwIfAborted();
 			try {
 				return await this.fetchStreamInfo(roomId);
 			} catch (err) {
 				if (err instanceof StreamFetchError) {
+					this.emit("waiting", {
+						username: this.username,
+						phase: "stream",
+						elapsed: (Date.now() - waitStart) / 1e3
+					});
 					await sleep(maxInterval);
 					continue;
 				}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "tokwatchr",
-	"version": "0.4.4",
+	"version": "0.5.0",
 	"description": "Download TikTok livestreams. Given a username, download the livestream.",
 	"type": "module",
 	"main": "./dist/index.mjs",

package/src/TikTokLiveDownloader.ts

@@ -320,6 +320,16 @@ export class TikTokLiveDownloader {
 			// biome-ignore lint/style/noNonNullAssertion: at least one result
 			return finalResults[finalResults.length - 1]!;
 		} catch (err) {
+			// One-shot waiting feedback for startRecording() users
+			// when the stream isn't active yet.
+			if (err instanceof StreamFetchError) {
+				this.emit("waiting", {
+					username: this.username,
+					phase: "stream",
+					elapsed: 0,
+				});
+			}
+
 			// Await any background remuxes before shutting down,
 			// so they can finish producing .mp4 and delete temp .ts files.
 			if (pendingRemuxes.length > 0) {
@@ -368,6 +378,7 @@ export class TikTokLiveDownloader {
 	private async resolveRoomIdWithRetry(): Promise<string> {
 		const interval = this.options.checkInterval;
 		const maxInterval = Math.max(interval, 180_000);
+		const waitStart = Date.now();
 
 		while (true) {
 			this.abortController.signal?.throwIfAborted();
@@ -377,6 +388,11 @@ export class TikTokLiveDownloader {
 				return roomId;
 			}
 
+			this.emit("waiting", {
+				username: this.username,
+				phase: "room",
+				elapsed: (Date.now() - waitStart) / 1_000,
+			});
 			await sleep(maxInterval);
 		}
 	}
@@ -401,6 +417,7 @@ export class TikTokLiveDownloader {
 	private async pollStreamInfo(roomId: string): Promise<StreamInfo> {
 		const interval = this.options.checkInterval;
 		const maxInterval = Math.max(interval, 180_000);
+		const waitStart = Date.now();
 
 		while (true) {
 			this.abortController.signal?.throwIfAborted();
@@ -409,6 +426,11 @@ export class TikTokLiveDownloader {
 				return await this.fetchStreamInfo(roomId);
 			} catch (err) {
 				if (err instanceof StreamFetchError) {
+					this.emit("waiting", {
+						username: this.username,
+						phase: "stream",
+						elapsed: (Date.now() - waitStart) / 1_000,
+					});
 					await sleep(maxInterval);
 					continue;
 				}

package/src/index.ts

@@ -32,6 +32,7 @@ export type {
 	StreamQualityKey,
 	TikTokLiveDownloaderEvents,
 	TikTokLiveDownloaderOptions,
+	WaitingInfo,
 } from "./types.js";
 
 // ─── Quality utilities ────────────────────────────────────

package/src/types.ts

@@ -114,7 +114,18 @@ export interface CookieJarLike {
 
 // ─── Events ───────────────────────────────────────────────
 
+export interface WaitingInfo {
+	/** The username being waited on. */
+	username: string;
+	/** Which phase we're waiting in: "room" = looking for a room, "stream" = stream not active. */
+	phase: "room" | "stream";
+	/** Seconds elapsed since this phase started. */
+	elapsed: number;
+}
+
 export interface TikTokLiveDownloaderEvents {
+	/** Emitted periodically while waiting for a room or stream to become active. */
+	waiting: [info: WaitingInfo];
 	/** Emitted when a live stream is detected and we're about to start recording. */
 	start: [info: StreamInfo];
 	/** Emitted periodically (every ~1s) during recording with current stats. */