@zfadhli/tokrec 0.13.0 → 0.15.0

package/src/io/tiktok/parse.ts

@@ -0,0 +1,171 @@
+export interface SigiState {
+  LiveRoom?: {
+    liveRoomStatus?: number
+    liveRoomUserInfo?: {
+      user?: {
+        id?: string | number
+        roomId?: string | number
+      }
+      liveRoom?: {
+        status?: number // 2 = live, 4 = offline
+        title?: string
+        startTime?: number
+        streamData?: {
+          pull_data?: {
+            stream_data?: string // JSON string with FLV/HLS URLs
+          }
+        }
+      }
+    }
+  }
+  UserModule?: {
+    users?: {
+      [username: string]: {
+        id?: string // numeric user ID
+        uniqueId?: string
+        roomId?: string | { id: string }
+      }
+    }
+  }
+}
+
+// ─── HTML parsing ──────────────────────────────────────────
+
+/**
+ * @public Exported for testing.
+ */
+export function extractSigiState(html: string): SigiState | null {
+  const match = html.match(/<script\s+id="SIGI_STATE"\s+type="application\/json">(.*?)<\/script>/)
+  if (!match?.[1]) return null
+  try {
+    return JSON.parse(match[1]) as SigiState
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Extract the numeric user ID and optional room ID from TikTok's new
+ * page structure (__UNIVERSAL_DATA_FOR_REHYDRATION__).
+ *
+ * The profile page (/@user) includes "webapp.user-detail" which
+ * contains the user's numeric ID. When the user is live, the roomId
+ * is also embedded here.
+ *
+ * Returns { userId, roomId } where userId is always set when the data
+ * is found, and roomId is set only when the user is currently live.
+ *
+ * @public Exported for testing and fixture capture.
+ */
+export function extractUserFromUniversalData(html: string): {
+  userId: string | null
+  roomId: string | null
+} {
+  const match = html.match(
+    /<script\s+id="__UNIVERSAL_DATA_FOR_REHYDRATION__"\s+type="application\/json">(.*?)<\/script>/,
+  )
+  if (!match?.[1]) return { userId: null, roomId: null }
+  try {
+    const data = JSON.parse(match[1])
+    const scope = (data as Record<string, unknown>).__DEFAULT_SCOPE__ ?? data
+    const userDetail = scope?.["webapp.user-detail"]
+    const user = userDetail?.userInfo?.user
+    const userId = user?.id ? String(user.id) : null
+    const roomId = user?.roomId ? String(user.roomId) : null
+    return { userId, roomId }
+  } catch {
+    return { userId: null, roomId: null }
+  }
+}
+
+// ─── Stream URL extraction ─────────────────────────────────
+
+/**
+ * Fast-path: extract stream URL from the known SIGI_STATE location.
+ * This covers ~95% of cases without needing a full recursive search.
+ *
+ * Prefers FLV (lower latency) over HLS/other protocols.
+ */
+export function extractStreamUrlFast(
+  liveRoom: NonNullable<NonNullable<SigiState["LiveRoom"]>["liveRoomUserInfo"]>["liveRoom"],
+): string | null {
+  try {
+    const raw = liveRoom?.streamData?.pull_data?.stream_data
+    if (!raw) return null
+    const parsed = JSON.parse(raw) as Record<string, unknown>
+    const data = (parsed as Record<string, unknown>)?.data as Record<string, unknown> | undefined
+    if (!data) return null
+
+    // Try all known quality keys, preferring higher quality.
+    // FLV is preferred (lower latency); HLS is the fallback.
+    const qualities = ["origin", "fhd", "uhd", "hd", "sd", "ld"]
+    for (const q of qualities) {
+      const entry = data[q] as { main?: { flv?: string; hls?: string } } | undefined
+      // Prefer FLV over HLS when both are available
+      const url = entry?.main?.flv ?? entry?.main?.hls
+      if (url) return url
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Brute-force recursive search for a stream URL anywhere in a JSON value.
+ * Survives TikTok changing key names or nesting structure.
+ *
+ * Prefers FLV over HLS when both are present in the response.
+ *
+ * Inspired by PR #430 (Michele0303/tiktok-live-recorder).
+ */
+export function findStreamUrlRecursively(obj: unknown): string | null {
+  // Collect all candidate URLs with their preference
+  const flvUrls: string[] = []
+  const m3u8Urls: string[] = []
+
+  function walk(value: unknown): void {
+    if (typeof value === "string") {
+      // Direct URL match
+      if (
+        (value.startsWith("http://") || value.startsWith("https://")) &&
+        (value.includes(".flv") || value.includes(".m3u8"))
+      ) {
+        if (value.includes(".flv")) {
+          flvUrls.push(value)
+        } else {
+          m3u8Urls.push(value)
+        }
+        return
+      }
+      // JSON-encoded string — parse and recurse
+      if (value.startsWith("{") || value.startsWith("[")) {
+        try {
+          walk(JSON.parse(value))
+        } catch {
+          // skip
+        }
+      }
+      return
+    }
+
+    if (value && typeof value === "object") {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          walk(item)
+        }
+      } else {
+        for (const val of Object.values(value as Record<string, unknown>)) {
+          walk(val)
+        }
+      }
+    }
+  }
+
+  walk(obj)
+
+  // Prefer FLV (lower latency) over HLS
+  if (flvUrls.length > 0) return flvUrls[0] as string
+  if (m3u8Urls.length > 0) return m3u8Urls[0] as string
+  return null
+}

package/src/io/tiktok/webcast.ts

@@ -0,0 +1,162 @@
+import type { RoomRef, StreamRef } from "../../core/verdict"
+import type { HttpClient } from "../http"
+import { findStreamUrlRecursively } from "./parse"
+
+const WEBCAST_BASE = "https://webcast.tiktok.com"
+
+/**
+ * Discriminated room/info result: refusals (notably status_code 4003110)
+ * and transport failures surface as `{ ok: false }` instead of null.
+ * `statusCode: 0` means the request threw before a status was read.
+ */
+export type RoomApiResult<T> =
+  | { ok: true; value: T | null }
+  | { ok: false; statusCode: number; body: string }
+
+/** Authoritative room/info facts: the room plus its stream URL when present. */
+export interface RoomFacts {
+  readonly room: RoomRef
+  readonly stream: StreamRef | null
+}
+
+/** What discovery sources consume. `createWebcastApi` is the only implementation. */
+export interface WebcastReader {
+  fetchFromRoomApi: <T>(
+    roomId: string,
+    extract: (data: Record<string, unknown>) => T | null,
+  ) => Promise<RoomApiResult<T>>
+  fetchCheckAlive: (roomId: string) => Promise<boolean>
+  fetchStreamUrlFromApi: (roomId: string) => Promise<RoomApiResult<string>>
+  /** room/info as domain facts; 4003110 comes back as `{ ok: false }`. */
+  roomInfo: (roomId: string) => Promise<RoomApiResult<RoomFacts>>
+  /** Resolve a 4003110 refusal: alive → restricted candidate, else offline. */
+  refusedRoom: (roomId: string, title: string | null) => Promise<RoomRef>
+}
+
+export function createWebcastApi(
+  http: HttpClient,
+  debug: (msg: string) => void,
+  signal?: AbortSignal,
+): WebcastReader {
+  /**
+   * Shared boilerplate for Webcast room/info API calls.
+   * Handles URL construction, HTTP GET, JSON parsing, and error handling.
+   * Room-gate refusals (status_code 4003110) are reported to the caller
+   * instead of being collapsed into null; callers map failures.
+   * The caller provides an extractor for the response data.
+   */
+  async function fetchFromRoomApi<T>(
+    roomId: string,
+    extract: (data: Record<string, unknown>) => T | null,
+  ): Promise<RoomApiResult<T>> {
+    try {
+      const url = `${WEBCAST_BASE}/webcast/room/info/?aid=1988&room_id=${roomId}&type=live`
+      const res = await http.get(url, signal)
+      debug(`fetchFromRoomApi: roomId=${roomId} status=${res.status}, ok=${res.ok}`)
+      if (!res.ok) return { ok: false, statusCode: res.status, body: "" }
+
+      const text = await res.text()
+      debug(`fetchFromRoomApi: roomId=${roomId} returned ${text.length} bytes`)
+      if (text.length === 0) return { ok: true, value: null }
+
+      const data = JSON.parse(text) as Record<string, unknown>
+
+      // status_code 4003110 = age-protected/restricted room: report it
+      if ((data as { status_code?: unknown }).status_code === 4003110) {
+        return { ok: false, statusCode: 4003110, body: text }
+      }
+
+      return { ok: true, value: extract(data) }
+    } catch {
+      // statusCode 0 = transport/parse failure before a status was available.
+      return { ok: false, statusCode: 0, body: "" }
+    }
+  }
+
+  /**
+   * Check if a room is currently alive using the lightweight
+   * /webcast/room/check_alive/ endpoint.
+   *
+   * This is faster and cheaper than fetching the full room/info response.
+   * Returns `true` if the room is live, `false` otherwise (including errors).
+   *
+   * Endpoint: /webcast/room/check_alive/?aid=1988&region=CH&room_ids={id}&user_is_login=true
+   * Response: { "data": [{ "alive": true/false, "room_id": "..." }] }
+   */
+  async function fetchCheckAlive(roomId: string): Promise<boolean> {
+    try {
+      const url = `${WEBCAST_BASE}/webcast/room/check_alive/?aid=1988&region=CH&room_ids=${roomId}&user_is_login=true`
+      const res = await http.get(url, signal)
+      debug(`fetchCheckAlive: roomId=${roomId} status=${res.status}, ok=${res.ok}`)
+      if (!res.ok) return false
+
+      const text = await res.text()
+      debug(`fetchCheckAlive: roomId=${roomId} returned ${text.length} bytes`)
+      if (text.length === 0) return false
+
+      const data = JSON.parse(text) as Record<string, unknown>
+      const items = data?.data as Array<Record<string, unknown>> | undefined
+      const alive = items?.[0]?.alive === true
+      debug(`fetchCheckAlive: roomId=${roomId} alive=${alive}`)
+      return alive
+    } catch (err) {
+      debug(
+        `fetchCheckAlive: roomId=${roomId} error — ${err instanceof Error ? err.message : String(err)}`,
+      )
+      return false
+    }
+  }
+
+  /**
+   * Resolve a 4003110 room-gate refusal via check_alive: the room is live
+   * (restricted) when alive, offline otherwise. Single home for this mapping.
+   */
+  async function refusedRoom(roomId: string, title: string | null): Promise<RoomRef> {
+    debug(`refusedRoom: room/info refused roomId=${roomId} (status_code 4003110)`)
+    const live = await fetchCheckAlive(roomId)
+    return { id: roomId, title, live }
+  }
+
+  /**
+   * Fetch room/info as domain facts. Requires a known roomId. A 4003110
+   * refusal stays `{ ok: false, statusCode: 4003110 }` for the caller to map
+   * via `refusedRoom`.
+   */
+  async function roomInfo(roomId: string): Promise<RoomApiResult<RoomFacts>> {
+    const res = await fetchFromRoomApi<Record<string, unknown>>(
+      roomId,
+      (data) => (data as { data?: Record<string, unknown> }).data ?? null,
+    )
+    if (!res.ok) return res
+    const roomData = res.value
+    if (!roomData) return { ok: true, value: null }
+
+    const title = (roomData.title as string | undefined) ?? null
+    const streamUrl = findStreamUrlRecursively(roomData)
+    return {
+      ok: true,
+      value: {
+        room: { id: roomId, title, live: (roomData.status ?? 4) === 2 },
+        stream: streamUrl ? { url: streamUrl } : null,
+      },
+    }
+  }
+
+  /**
+   * Fetch stream URL from the Webcast API.
+   * Covers cases where SIGI_STATE doesn't include stream data.
+   * Refusals (4003110) and transport failures are reported so callers
+   * can distinguish restricted rooms from missing URLs.
+   */
+  async function fetchStreamUrlFromApi(roomId: string): Promise<RoomApiResult<string>> {
+    return fetchFromRoomApi(roomId, (data) => findStreamUrlRecursively(data))
+  }
+
+  return {
+    fetchFromRoomApi,
+    fetchCheckAlive,
+    fetchStreamUrlFromApi,
+    roomInfo,
+    refusedRoom,
+  }
+}