@zfadhli/tokrec 0.13.0 → 0.15.2

package/src/io/tiktok/client.ts

@@ -0,0 +1,114 @@
+/**
+ * TikTok API — resolves room IDs, live status, and stream URLs.
+ *
+ * `createTikTokClient` is a thin orchestrator: per-user cache, cache invalidation,
+ * and `discover()` over sources returning `Candidate`s. The chain turns
+ * failures into evidence instead of aborting. `getVerdict` is the only
+ * public verdict surface.
+ *
+ * Architecture:
+ *   createTikTokClient(httpClient) → { isRoomAlive, getLiveUrl, getVerdict }
+ *
+ * All public methods share a per-tick cache so the page is fetched at most once
+ * per poll cycle. The optional `signal` aborts in-flight HTTP requests.
+ *
+ * Note: The room/enter Webcast endpoint has been deprecated due to frequent
+ * 403 errors. All lookups go through room/info (reliable for live + offline).
+ */
+
+import type { Logger } from "../../core/log"
+import { isLiveReason, type Verdict, verdictOf } from "../../core/verdict"
+import type { HttpClient } from "../http"
+import { type DiscoverySource, discover, type ResolveContext } from "./discovery/chain"
+import { createApiLiveSource, createProfileSource } from "./discovery/fallback"
+import { createPageSource } from "./discovery/page"
+import { createPageFetcher } from "./page"
+import { createWebcastApi } from "./webcast"
+
+export interface TikTokClient {
+  /** Check if a room is currently live. */
+  isRoomAlive(roomId: string): Promise<boolean>
+  /** Get the best-quality FLV stream URL for a room. Returns null on failure. */
+  getLiveUrl(roomId: string): Promise<string | null>
+  /** Full per-tick verdict with reason, refs, evidence trail, and failure. */
+  getVerdict(user: string): Promise<Verdict>
+  /** Invalidate per-tick cache (call at start of each poll tick). */
+  invalidateCache(): void
+}
+
+export function createTikTokClient(
+  http: HttpClient,
+  logger?: Logger,
+  showDebug?: boolean,
+  signal?: AbortSignal,
+): TikTokClient {
+  // Debug logging helper — writes to stderr only when --debug is passed.
+  const debug = (msg: string) => {
+    logger?.debug(msg)
+    if (showDebug) process.stderr.write(`[API_DEBUG] ${msg}\n`)
+  }
+  let cached: Verdict | null = null
+  let cachedUser = ""
+  const webcast = createWebcastApi(http, debug, signal)
+  const tryFetchPage = createPageFetcher(http, debug, signal)
+  const sources: DiscoverySource[] = [
+    createPageSource(),
+    createApiLiveSource(),
+    createProfileSource(),
+  ]
+
+  async function ensureCache(user: string): Promise<Verdict> {
+    if (cached && cachedUser === user) return cached
+    cached = await resolveVerdict(user)
+    cachedUser = user
+    return cached
+  }
+
+  function invalidateCache(): void {
+    cached = null
+    cachedUser = ""
+  }
+
+  return {
+    invalidateCache,
+
+    async getVerdict(user: string): Promise<Verdict> {
+      return ensureCache(user)
+    },
+
+    async isRoomAlive(roomId: string): Promise<boolean> {
+      if (cached?.room && String(cached.room.id) === String(roomId)) {
+        return isLiveReason(cached.reason)
+      }
+      // Use the lightweight check_alive endpoint instead of re-fetching
+      // the full room/info response.
+      return webcast.fetchCheckAlive(roomId)
+    },
+
+    async getLiveUrl(roomId: string): Promise<string | null> {
+      if (cached?.room && String(cached.room.id) === String(roomId) && cached.stream) {
+        return cached.stream.url
+      }
+      // Room ID, not a username: never route this through ensureCache.
+      const res = await webcast.fetchStreamUrlFromApi(roomId)
+      return res.ok ? res.value : null
+    },
+  }
+
+  // ─── Internal: discovery chain → one verdict ───
+
+  async function resolveVerdict(user: string): Promise<Verdict> {
+    const ctx: ResolveContext = { user, http, debug, fetchPage: tryFetchPage, webcast }
+    const { candidate, evidence } = await discover(sources, ctx)
+    switch (candidate.kind) {
+      case "room":
+        return verdictOf({ room: candidate.room, stream: candidate.stream, evidence })
+      case "denied":
+        return verdictOf({ room: candidate.room, denied: true, evidence })
+      case "failed":
+        return verdictOf({ failure: candidate.error, evidence })
+      case "miss":
+        return verdictOf({ evidence })
+    }
+  }
+}

package/src/io/tiktok/discovery/chain.ts

@@ -0,0 +1,146 @@
+/**
+ * Discovery chain — one idea in one file: a source reports facts, the chain
+ * turns every outcome (including a throw) into evidence, and the first room or
+ * gate refusal ends it.
+ *
+ * Types, candidate constructors, and the runner live together because they are
+ * a single contract; splitting them across `types.ts` and `candidates.ts` only
+ * added import edges.
+ */
+
+import type { Evidence, EvidenceOutcome, RoomRef, SourceId, StreamRef } from "../../../core/verdict"
+import type { HttpClient } from "../../http"
+import type { WebcastReader } from "../webcast"
+
+/**
+ * What one discovery source found. `room`/`denied` end the chain; `miss` and
+ * `failed` let the next source try — a throw is evidence, never a dead end.
+ */
+export type Candidate =
+  | { kind: "room"; room: RoomRef; stream: StreamRef | null; source: SourceId }
+  | { kind: "denied"; room: RoomRef; code: number; source: SourceId }
+  | { kind: "miss"; note: string }
+  | { kind: "failed"; error: Error }
+
+export interface ResolveContext {
+  user: string
+  http: HttpClient
+  debug: (msg: string) => void
+  fetchPage: (user: string, path: string) => Promise<{ html: string; baseUrl: string } | null>
+  webcast: WebcastReader
+}
+
+export interface DiscoverySource {
+  readonly id: "page" | "api-live" | "profile"
+  find(ctx: ResolveContext): Promise<Candidate>
+}
+
+// ─── candidate constructors ────────────────────────────────
+
+/** Nothing found here — let the next source try. */
+export function miss(note: string): Candidate {
+  return { kind: "miss", note }
+}
+
+/** A transport/parse failure. The chain keeps going; it only wins over a miss. */
+export function failed(error: unknown): Candidate {
+  return { kind: "failed", error: error instanceof Error ? error : new Error(String(error)) }
+}
+
+/**
+ * Room live with a stream URL. Uses `knownUrl` when the page already carried
+ * it; otherwise asks the Webcast API. A 4003110 refusal becomes `denied`.
+ */
+export async function withStream(
+  ctx: ResolveContext,
+  room: RoomRef,
+  source: SourceId,
+  knownUrl: string | null,
+): Promise<Candidate> {
+  if (knownUrl) return { kind: "room", room, stream: { url: knownUrl }, source }
+  const res = await ctx.webcast.fetchStreamUrlFromApi(room.id)
+  if (res.ok) {
+    return { kind: "room", room, stream: res.value ? { url: res.value } : null, source }
+  }
+  if (res.statusCode === 4003110) return refused(ctx, room.id, room.title, source)
+  return { kind: "room", room, stream: null, source }
+}
+
+/** Authoritative room/info lookup: the single 4003110 consumer for room IDs. */
+export async function fromRoomInfo(
+  ctx: ResolveContext,
+  roomId: string,
+  source: SourceId,
+): Promise<Candidate> {
+  const res = await ctx.webcast.roomInfo(roomId)
+  if (res.ok) {
+    if (!res.value) return miss(`room/info returned no data for ${roomId}`)
+    return { kind: "room", room: res.value.room, stream: res.value.stream, source }
+  }
+  if (res.statusCode === 4003110) return refused(ctx, roomId, null, source)
+  if (res.statusCode === 0) return failed(new Error(`room/info transport failure for ${roomId}`))
+  return miss(`room/info HTTP ${res.statusCode} for ${roomId}`)
+}
+
+/** Gate refusal: check_alive decides whether the room is live (restricted) or offline. */
+export async function refused(
+  ctx: ResolveContext,
+  roomId: string,
+  title: string | null,
+  source: SourceId,
+): Promise<Candidate> {
+  const room = await ctx.webcast.refusedRoom(roomId, title)
+  return { kind: "denied", room, code: 4003110, source }
+}
+
+// ─── runner ────────────────────────────────────────────────
+
+function outcomeOf(candidate: Candidate): EvidenceOutcome {
+  switch (candidate.kind) {
+    case "room":
+      return "hit"
+    case "denied":
+      return "denied"
+    case "failed":
+      return "error"
+    case "miss":
+      return "miss"
+  }
+}
+
+/**
+ * Run discovery sources in order. A throw — sync or async — becomes a
+ * `failed` candidate and the chain continues: the `probe.ts:154` dead end,
+ * inverted. A room or a gate refusal ends the chain; the first failure
+ * outranks a later miss.
+ */
+export async function discover(
+  sources: readonly DiscoverySource[],
+  ctx: ResolveContext,
+): Promise<{ candidate: Candidate; evidence: Evidence[] }> {
+  const evidence: Evidence[] = []
+  let best: Candidate = { kind: "miss", note: "no sources configured" }
+
+  for (const source of sources) {
+    const candidate = await (async (): Promise<Candidate> => {
+      try {
+        return await source.find(ctx)
+      } catch (error) {
+        ctx.debug(
+          `discover: ${source.id} threw — ${error instanceof Error ? error.message : error}`,
+        )
+        return { kind: "failed", error: error instanceof Error ? error : new Error(String(error)) }
+      }
+    })()
+    evidence.push({
+      source:
+        candidate.kind === "room" || candidate.kind === "denied" ? candidate.source : source.id,
+      outcome: outcomeOf(candidate),
+    })
+    if (candidate.kind === "room" || candidate.kind === "denied") return { candidate, evidence }
+    // First failure is the root cause; a later failure must not overwrite it.
+    if (candidate.kind === "failed" && best.kind !== "failed") best = candidate
+  }
+
+  return { candidate: best, evidence }
+}

package/src/io/tiktok/discovery/fallback.ts

@@ -0,0 +1,88 @@
+/**
+ * Fallback sources tried after the page: TikTok's own `/api-live/` endpoint,
+ * then the profile page's universal data. Both are thin, both fail into
+ * `miss`/`failed` so the chain keeps its evidence trail.
+ */
+
+import type { RoomRef } from "../../../core/verdict"
+import { extractUserFromUniversalData } from "../parse"
+import {
+  type Candidate,
+  type DiscoverySource,
+  failed,
+  fromRoomInfo,
+  miss,
+  type ResolveContext,
+  withStream,
+} from "./chain"
+
+export function createApiLiveSource(): DiscoverySource {
+  return {
+    id: "api-live",
+    async find(ctx: ResolveContext): Promise<Candidate> {
+      try {
+        const url = `https://www.tiktok.com/api-live/user/room/?aid=1988&uniqueId=${encodeURIComponent(ctx.user)}&sourceType=54`
+        const res = await ctx.http.get(url)
+        ctx.debug(`fetchLiveInfoFromApi: ${url} status=${res.status}`)
+        if (!res.ok) return miss(`api-live HTTP ${res.status}`)
+
+        const text = await res.text()
+        ctx.debug(`fetchLiveInfoFromApi: returned ${text.length} bytes`)
+        if (text.length === 0) return miss("api-live: empty body")
+
+        const data = JSON.parse(text) as Record<string, unknown>
+        const userData = (data?.data as Record<string, unknown> | undefined)?.user as
+          | { roomId?: string; status?: number; uniqueId?: string }
+          | undefined
+
+        if (!userData?.roomId) {
+          ctx.debug("fetchLiveInfoFromApi: no roomId in API response")
+          return miss("api-live: no roomId")
+        }
+
+        // status: 2 = live, 4 = offline, 1 = ...
+        const room: RoomRef = {
+          id: String(userData.roomId),
+          title: null,
+          live: userData.status === 2,
+        }
+        ctx.debug(
+          `fetchLiveInfoFromApi: roomId=${room.id}, status=${userData.status}, live=${room.live}`,
+        )
+
+        if (!room.live) return { kind: "room", room, stream: null, source: "api-live" }
+        return withStream(ctx, room, "api-live", null)
+      } catch (error) {
+        return failed(error)
+      }
+    },
+  }
+}
+
+export function createProfileSource(): DiscoverySource {
+  return {
+    id: "profile",
+    async find(ctx: ResolveContext): Promise<Candidate> {
+      try {
+        const page = await ctx.fetchPage(ctx.user, "")
+        if (!page) {
+          ctx.debug("fetchLiveInfoFromProfile: all domains blocked for profile page")
+          return miss("profile: page blocked")
+        }
+        ctx.debug(
+          `fetchLiveInfoFromProfile: returned ${page.html.length} bytes (${page.baseUrl}), first 300: ${page.html.slice(0, 300).replace(/\n/g, "\\n")}`,
+        )
+        const { userId, roomId } = extractUserFromUniversalData(page.html)
+        if (!userId) return miss("profile: no universal data")
+        // No roomId means the user is offline (room/enter was unreliable).
+        if (!roomId) return miss("profile: user offline")
+
+        // If roomId is embedded in the profile page, the user is live.
+        // Use room/info which works reliably for both live and offline rooms.
+        return fromRoomInfo(ctx, roomId, "room-info")
+      } catch (error) {
+        return failed(error)
+      }
+    },
+  }
+}

package/src/io/tiktok/discovery/page.ts

@@ -0,0 +1,142 @@
+import type { RoomRef } from "../../../core/verdict"
+import type { SigiState } from "../parse"
+import {
+  extractSigiState,
+  extractStreamUrlFast,
+  extractUserFromUniversalData,
+  findStreamUrlRecursively,
+} from "../parse"
+import {
+  type Candidate,
+  type DiscoverySource,
+  fromRoomInfo,
+  miss,
+  type ResolveContext,
+  withStream,
+} from "./chain"
+
+/**
+ * Page source: server-rendered SIGI_STATE first, then the async-loaded legacy
+ * module, then `__UNIVERSAL_DATA_FOR_REHYDRATION__`. Throws propagate to the
+ * chain, which records them and moves on — never a dead end.
+ */
+export function createPageSource(): DiscoverySource {
+  return {
+    id: "page",
+    async find(ctx: ResolveContext): Promise<Candidate> {
+      let sigi: SigiState | null = null
+      let html = ""
+      // A `failed` sub-step is not terminal: legacy + universal-data fallbacks
+      // still get their chance. It is returned only if nothing else hit.
+      let failure: Extract<Candidate, { kind: "failed" }> | null = null
+      const take = (candidate: Candidate): Candidate | null => {
+        if (candidate.kind === "room" || candidate.kind === "denied") return candidate
+        if (candidate.kind === "failed") failure ??= candidate
+        return null
+      }
+
+      const page = await ctx.fetchPage(ctx.user, "/live")
+      if (!page) {
+        ctx.debug("fetchLiveInfo: all domains blocked for /live page")
+        // Fall through to universal data / profile page fallback
+        html = ""
+      } else {
+        html = page.html
+        ctx.debug(
+          `fetchLiveInfo: /live returned ${html.length} bytes (${page.baseUrl}), first 300: ${html.slice(0, 300).replace(/\n/g, "\\n")}`,
+        )
+
+        sigi = extractSigiState(html)
+        ctx.debug(`fetchLiveInfo: SIGI_STATE ${sigi ? "found" : "not found"}`)
+
+        if (sigi) {
+          const liveRoom = sigi.LiveRoom?.liveRoomUserInfo?.liveRoom
+          const userInfo = sigi.LiveRoom?.liveRoomUserInfo?.user
+
+          ctx.debug(
+            `fetchLiveInfo: liveRoom=${!!liveRoom}, userInfo=${!!userInfo}, userInfo.roomId=${userInfo?.roomId ?? "null"}`,
+          )
+
+          // ── Primary path: liveRoom is populated (server-rendered) ──
+          if (liveRoom && userInfo?.roomId) {
+            const room: RoomRef = {
+              id: String(userInfo.roomId),
+              title: liveRoom.title ?? null,
+              live: liveRoom.status === 2, // 2 = live, 4 = offline
+            }
+            ctx.debug(
+              `fetchLiveInfo: primary path — roomId=${room.id}, status=${liveRoom.status}, live=${room.live}`,
+            )
+            if (!room.live) return { kind: "room", room, stream: null, source: "sigi" }
+
+            // Extract stream URL: try SIGI_STATE first, then Webcast API fallback
+            const knownUrl = extractStreamUrlFast(liveRoom) ?? findStreamUrlRecursively(sigi)
+            return withStream(ctx, room, "sigi", knownUrl)
+          }
+
+          // ── Fallback: userInfo has roomId, but liveRoom is async-loaded ──
+          // TikTok may omit liveRoom from the server-rendered page and load it
+          // via JavaScript. Query the Webcast API directly — it's authoritative.
+          if (userInfo?.roomId) {
+            const roomId = String(userInfo.roomId)
+            ctx.debug(`fetchLiveInfo: userInfo fallback — roomId=${roomId}, querying Webcast API`)
+            const found = take(await fromRoomInfo(ctx, roomId, "room-info"))
+            ctx.debug(
+              `fetchLiveInfo: Webcast API ${found ? "returned room info" : "returned null"}`,
+            )
+            if (found) return found
+          }
+
+          // ── Legacy fallback: async-loaded SIGI_STATE ──
+          ctx.debug("fetchLiveInfo: trying legacy fallback (UserModule)")
+          const legacy = take(await sigiLegacy(sigi, ctx))
+          ctx.debug(`fetchLiveInfo: legacy fallback ${legacy ? "succeeded" : "returned null"}`)
+          if (legacy) return legacy
+        } // end if (sigi)
+      } // end else (page loaded)
+
+      // ── Universal data from the already-fetched /live html ──
+      // TikTok migrated from SIGI_STATE to __UNIVERSAL_DATA_FOR_REHYDRATION__.
+      // The /live page may not have it, so try the main profile page.
+      ctx.debug(`fetchLiveInfo: trying universal data fallback (html length ${html.length})`)
+      const { roomId } = extractUserFromUniversalData(html)
+      ctx.debug(`fetchLiveInfo: universal data roomId=${roomId ?? "null"}`)
+      if (roomId) {
+        const found = take(await fromRoomInfo(ctx, roomId, "room-info"))
+        ctx.debug(
+          `fetchLiveInfo: universal data Webcast API ${found ? "succeeded" : "returned null"}`,
+        )
+        if (found) return found
+      }
+      return failure ?? miss("page: no room id")
+    },
+  }
+}
+
+/**
+ * Secondary live-info extraction when SIGI_STATE's LiveRoom data is
+ * async-loaded. Uses LiveRoom.liveRoomStatus for the live flag and
+ * UserModule.users[user].roomId for the room ID. Stream URL comes from the
+ * Webcast API (room/info/) as a final fallback.
+ */
+async function sigiLegacy(sigi: SigiState, ctx: ResolveContext): Promise<Candidate> {
+  const isLive = sigi.LiveRoom?.liveRoomStatus === 2 // 2 = live
+
+  // Try to get roomId from UserModule (usually populated even when LiveRoom is not)
+  const userModule = sigi.UserModule?.users?.[ctx.user]
+  let roomId: string | null = null
+
+  if (userModule?.roomId) {
+    roomId =
+      typeof userModule.roomId === "object"
+        ? String((userModule.roomId as { id: string }).id ?? "")
+        : String(userModule.roomId)
+  }
+
+  // No roomId available — treat as offline (room/enter was unreliable).
+  if (!roomId) return miss("sigi-legacy: no roomId")
+
+  const room: RoomRef = { id: roomId, title: null, live: isLive }
+  if (!isLive) return { kind: "room", room, stream: null, source: "sigi" }
+  return withStream(ctx, room, "sigi", null)
+}

package/src/io/tiktok/page.ts

@@ -0,0 +1,42 @@
+import type { HttpClient } from "../http"
+
+const TIKTOK_BASES = ["https://www.tiktok.com", "https://m.tiktok.com"]
+
+export function createPageFetcher(
+  http: HttpClient,
+  debug: (msg: string) => void,
+  signal?: AbortSignal,
+): (user: string, path: string) => Promise<{ html: string; baseUrl: string } | null> {
+  /**
+   * Try to fetch a TikTok user page from multiple domains.
+   * www.tiktok.com is increasingly blocked by Slardar WAF; m.tiktok.com
+   * often has different bot protection and may succeed.
+   * Returns the HTML and the base URL that worked, or null if all fail.
+   */
+  async function tryFetchPage(
+    user: string,
+    path: string,
+  ): Promise<{ html: string; baseUrl: string } | null> {
+    for (const base of TIKTOK_BASES) {
+      const url = `${base}/@${user}${path}`
+      const res = await http.get(url, signal)
+      debug(`tryFetchPage: ${url} status=${res.status}, ok=${res.ok}`)
+      if (!res.ok) continue
+
+      const html = await res.text()
+      // Reject Slardar WAF challenge pages (small + keyword)
+      if (html.length < 5000 || html.includes("SlardarWAF")) {
+        debug(
+          `tryFetchPage: ${url} WAF blocked (${html.length} bytes, slardar=${html.includes("SlardarWAF")})`,
+        )
+        continue
+      }
+
+      debug(`tryFetchPage: ${url} succeeded (${html.length} bytes)`)
+      return { html, baseUrl: base }
+    }
+    return null
+  }
+
+  return tryFetchPage
+}