@zfadhli/tokrec 0.13.0 → 0.15.2

package/src/app/config.ts

@@ -0,0 +1,178 @@
+/**
+ * Config — types, defaults, and normalization for the recorder.
+ * The single source of truth for every user-facing option.
+ */
+
+import { TikTokError } from "../core/errors"
+import type { Verdict } from "../core/verdict"
+
+/**
+ * TikTok cookie key-value pairs extracted from Firefox or cookies.json.
+ * Includes session cookies (sessionid_ss, tt-target-idc) and any WAF
+ * bypass cookies needed to avoid Slardar challenges on www.tiktok.com.
+ */
+export type CookieAuth = Record<string, string>
+
+export type LogLevel = "debug" | "info" | "warn" | "error"
+
+/**
+ * Machine-readable reason for a LIVE status verdict — lives in `domain/verdict.ts`.
+ */
+export type { LiveReason } from "../core/verdict"
+
+export interface RecorderConfig {
+  /** TikTok username (required) */
+  user: string
+  /** Output directory for recordings (default: ./recordings) */
+  outputDir?: string
+  /** Polling interval in minutes (default: 3) */
+  interval?: number
+  /** Max recording duration in seconds (default: 0 — unlimited). CLI accepts minutes, converted internally. */
+  duration?: number
+  /** HTTP proxy URL (e.g. http://127.0.0.1:8080) */
+  proxy?: string
+  /** Path to cookies.json (default: ./cookies.json) */
+  cookiesPath?: string
+  /** Cookie auth loaded from cookies.json */
+  cookies?: CookieAuth
+  /** Log level (default: info) */
+  logLevel?: LogLevel
+  /** Whether to print logs to console (default: true). Set false when using Display-based UI. */
+  logConsole?: boolean
+  /** Segment duration in minutes (default: 0 — disabled). When >= 1, the recording is split into segments of this length. */
+  segmentMinutes?: number
+  /** Normalize audio loudness via EBU R128 (default: false). */
+  normalizeAudio?: boolean
+  /** Target loudness in LUFS (default: -14). */
+  normalizeLoudness?: number
+  /** Audio codec for normalized output (default: peaknorm's default, "libopus"). */
+  normalizeCodec?: string
+  /** Audio bitrate for normalized output (default: peaknorm's default, "96k"). */
+  normalizeBitrate?: string
+  /**
+   * Max API requests per second (default: 5).
+   * Prevents TikTok WAF triggering on rapid polling or URL refresh loops.
+   * Set to 0 for unlimited (not recommended).
+   */
+  ratePerSecond?: number
+  /** Show API debug logging on stderr (default: false). */
+  debug?: boolean
+}
+
+export interface RecorderController {
+  /** Start the polling loop */
+  start(): Promise<void>
+  /** Gracefully stop (joins active recording, then exits) */
+  stop(): Promise<void>
+  /** Snapshot of current state */
+  getStatus(): RecorderStatus
+  /** Subscribe to events */
+  on<E extends keyof RecorderEventHandler>(event: E, handler: RecorderEventHandler[E]): void
+  /** Unsubscribe a previously registered event handler */
+  off<E extends keyof RecorderEventHandler>(event: E, handler: RecorderEventHandler[E]): void
+}
+
+export type Phase = "idle" | "polling" | "recording" | "segmenting" | "converting" | "stopped"
+
+export interface RecorderStatus {
+  state: Phase
+  user: string
+  currentFile?: string
+  sessionDuration?: number
+  lastPollTime?: string
+  lastError?: string
+}
+
+export type RecorderEvent = keyof RecorderEventHandler
+
+export interface RecordedFile {
+  file: string
+  duration: number
+  size: number
+}
+
+/** One recording lifecycle channel: start → download → processing → end. */
+export type RecordEvent =
+  | { phase: "start"; user: string; file: string }
+  | ({ phase: "download" } & RecordedFile)
+  | { phase: "segment"; status: "start"; input: string; outputPattern: string }
+  | { phase: "segment"; status: "end"; segments: number }
+  | { phase: "convert"; status: "start"; input: string }
+  | { phase: "convert"; status: "done"; input: string; output: string }
+  | { phase: "normalize"; status: "start"; file: string }
+  | { phase: "normalize"; status: "done"; input: string; output: string }
+  | { phase: "normalize"; status: "error"; input: string; error: string }
+  | ({ phase: "end" } & RecordedFile)
+
+/** One download progress sample. The finished-download shape is `RecordedFile`. */
+export interface DownloadProgress {
+  bytes: number
+  elapsed: number
+  speed: number
+}
+
+/** Download and normalize progress share one spinner in the CLI. */
+export type ProgressEvent =
+  | ({ kind: "download" } & DownloadProgress)
+  | { kind: "normalize"; file: string; percent: number; phase: "analyzing" | "normalizing" }
+
+export interface RecorderEventHandler {
+  verdict: (verdict: Verdict) => void
+  record: (event: RecordEvent) => void
+  progress: (event: ProgressEvent) => void
+  failure: (err: TikTokError) => void
+}
+
+/** A `RecorderConfig` with every default applied — what the recorder runs on. */
+export interface ResolvedConfig {
+  user: string
+  outputDir: string
+  interval: number
+  duration: number
+  proxy?: string
+  cookiesPath?: string
+  cookies?: CookieAuth
+  logLevel: LogLevel
+  logConsole: boolean
+  segmentMinutes: number
+  normalizeAudio: boolean
+  normalizeLoudness: number
+  normalizeCodec?: string
+  normalizeBitrate?: string
+  ratePerSecond: number
+  debug: boolean
+}
+
+/** Apply defaults once, at the entry point; nothing downstream re-reads `??`. */
+export function resolveConfig(config: RecorderConfig): ResolvedConfig {
+  return {
+    user: config.user,
+    outputDir: config.outputDir ?? ".",
+    interval: config.interval ?? 3,
+    duration: config.duration ?? 0,
+    proxy: config.proxy,
+    cookies: config.cookies,
+    cookiesPath: config.cookiesPath,
+    logLevel: config.logLevel ?? "info",
+    logConsole: config.logConsole ?? true,
+    segmentMinutes: config.segmentMinutes ?? 0,
+    normalizeAudio: config.normalizeAudio ?? false,
+    normalizeLoudness: config.normalizeLoudness ?? -14,
+    normalizeCodec: config.normalizeCodec,
+    normalizeBitrate: config.normalizeBitrate,
+    ratePerSecond: config.ratePerSecond ?? 5,
+    debug: config.debug ?? false,
+  }
+}
+
+export function validateConfig(config: RecorderConfig): void {
+  if (!config.user || config.user.trim().length === 0) {
+    throw new TikTokError("config-error", "--user is required")
+  }
+  if (config.interval !== undefined && config.interval < 1) {
+    throw new TikTokError("config-error", "--interval must be >= 1 minute")
+  }
+  if (config.duration !== undefined && config.duration < 0) {
+    throw new TikTokError("config-error", "--duration must be >= 0 seconds")
+  }
+}

package/src/app/events.ts

@@ -0,0 +1,46 @@
+/**
+ * Typed emitter over `node:events` — the four-channel recorder contract
+ * (`verdict`, `record`, `progress`, `failure`) with no listener bookkeeping of
+ * our own. `emit` swallows handler throws: a bad subscriber must not kill a
+ * recording.
+ */
+
+import { EventEmitter } from "node:events"
+import type { RecorderEvent, RecorderEventHandler } from "./config"
+
+export interface RecorderEventEmitter {
+  on<E extends RecorderEvent>(event: E, handler: RecorderEventHandler[E]): void
+  off<E extends RecorderEvent>(event: E, handler: RecorderEventHandler[E]): void
+  emit<E extends RecorderEvent>(event: E, ...args: Parameters<RecorderEventHandler[E]>): void
+  clear(): void
+}
+
+export function createEventEmitter(): RecorderEventEmitter {
+  const emitter = new EventEmitter()
+  const asListener = (handler: unknown) => handler as (...args: unknown[]) => void
+
+  function on<E extends RecorderEvent>(event: E, handler: RecorderEventHandler[E]): void {
+    emitter.on(event, asListener(handler))
+  }
+
+  function off<E extends RecorderEvent>(event: E, handler: RecorderEventHandler[E]): void {
+    emitter.off(event, asListener(handler))
+  }
+
+  function emit<E extends RecorderEvent>(
+    event: E,
+    ...args: Parameters<RecorderEventHandler[E]>
+  ): void {
+    try {
+      emitter.emit(event, ...args)
+    } catch {
+      // Never let an event handler crash the recorder.
+    }
+  }
+
+  function clear(): void {
+    emitter.removeAllListeners()
+  }
+
+  return { on, off, emit, clear }
+}

package/src/app/job.ts

@@ -0,0 +1,228 @@
+/**
+ * RecordingJob — owns one download's post-processing and the promises it
+ * spawns. `finish()` is idempotent so `stop()` can join without the recorder
+ * reaching into a shared array.
+ */
+
+import { statSync, unlinkSync, utimesSync } from "node:fs"
+import { join, parse } from "node:path"
+import { TikTokError } from "../core/errors"
+import type { Logger } from "../core/log"
+import type { Converter } from "../io/media/convert"
+import type { AudioNormalizer } from "../io/media/normalize"
+import type {
+  ProgressEvent,
+  RecordEvent,
+  RecordedFile,
+  RecorderConfig,
+  RecorderStatus,
+} from "./config"
+
+export interface RecordingJob {
+  readonly file: string
+  finish(): Promise<RecordedFile[]>
+}
+
+export interface RecordingJobDeps {
+  result: RecordedFile
+  cfg: Pick<RecorderConfig, "segmentMinutes">
+  logger: Logger
+  converter: Converter
+  audioNormalizer: AudioNormalizer | null
+  signal: AbortSignal
+  emitRecord: (event: RecordEvent) => void
+  emitProgress: (event: ProgressEvent) => void
+  emitFailure: (err: TikTokError) => void
+  setState: (partial: Partial<RecorderStatus>) => void
+}
+
+export function createRecordingJob(deps: RecordingJobDeps): RecordingJob {
+  let promise: Promise<RecordedFile[]> | null = null
+
+  return {
+    file: deps.result.file,
+    finish(): Promise<RecordedFile[]> {
+      promise ??= run(deps)
+      return promise
+    },
+  }
+}
+
+async function run(deps: RecordingJobDeps): Promise<RecordedFile[]> {
+  const { result, cfg, logger, signal } = deps
+  try {
+    if (statSync(result.file).size === 0) return []
+  } catch {
+    return []
+  }
+
+  try {
+    if (cfg.segmentMinutes && cfg.segmentMinutes >= 1) return await segment(deps)
+    return await convert(deps)
+  } catch (err) {
+    if (!signal.aborted) {
+      const tkErr = err instanceof TikTokError ? err : new TikTokError("unknown", String(err))
+      logger.error(`Recording processing failed: ${tkErr.message}`)
+      deps.setState({ lastError: tkErr.message })
+      deps.emitFailure(tkErr)
+    }
+    return []
+  } finally {
+    if (!signal.aborted) deps.setState({ state: "polling" })
+  }
+}
+
+async function segment(deps: RecordingJobDeps): Promise<RecordedFile[]> {
+  const { result, cfg, logger, signal } = deps
+  const parsed = parse(result.file)
+  const segmentTime = Math.max(1, (cfg.segmentMinutes ?? 20) * 60)
+  const outputPattern = join(parsed.dir, `${parsed.name}_part%d.mp4`)
+
+  logger.info(
+    `Segmenting: ${parsed.base} → ${parsed.name}_partN.mp4 (${cfg.segmentMinutes ?? 20} min each)`,
+  )
+  deps.setState({ state: "segmenting" })
+  deps.emitRecord({
+    phase: "segment",
+    status: "start",
+    input: result.file,
+    outputPattern,
+  })
+
+  let listing: string
+  try {
+    listing = await deps.converter.segment(result.file, segmentTime, outputPattern)
+  } catch (err) {
+    if (signal.aborted) return []
+    const msg = err instanceof Error ? err.message : String(err)
+    logger.error(`Segmenting failed: ${msg}`)
+    deps.setState({ lastError: `Segmenting failed: ${msg}` })
+    return convert(deps)
+  }
+
+  const segments = parseSegmentList(listing, segmentTime)
+  if (segments.length === 0) {
+    logger.warn("Segmenting produced no files — falling back to whole-file conversion")
+    return convert(deps)
+  }
+
+  const fileMtimeMs = statSync(result.file).mtimeMs
+  const recStartMs = fileMtimeMs - result.duration * 1000
+
+  try {
+    unlinkSync(result.file)
+    logger.info(`Deleted original: ${parsed.base}`)
+  } catch {
+    logger.warn(`Could not delete original: ${parsed.base}`)
+  }
+
+  const files: RecordedFile[] = []
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i]
+    if (!seg) continue
+    const stats = statSync(seg.file)
+    const recorded: RecordedFile = {
+      file: seg.file,
+      duration: seg.duration,
+      size: stats.size,
+    }
+    files.push(recorded)
+    deps.emitRecord({ phase: "end", ...recorded })
+    deps.emitRecord({
+      phase: "convert",
+      status: "done",
+      input: result.file,
+      output: seg.file,
+    })
+
+    const segStart = recStartMs + i * segmentTime * 1000
+    utimesSync(seg.file, new Date(segStart), new Date(segStart))
+  }
+
+  deps.emitRecord({ phase: "segment", status: "end", segments: files.length })
+
+  if (deps.audioNormalizer) {
+    for (const recorded of files) {
+      await normalize(deps, recorded.file)
+    }
+  }
+
+  deps.setState({
+    currentFile: files.at(-1)?.file ?? result.file,
+    sessionDuration: result.duration,
+  })
+  return files
+}
+
+async function convert(deps: RecordingJobDeps): Promise<RecordedFile[]> {
+  const { result, logger, signal } = deps
+  deps.setState({ state: "converting" })
+  deps.emitRecord({ phase: "convert", status: "start", input: result.file })
+
+  let mp4File: string
+  try {
+    mp4File = await deps.converter.convert(result.file)
+  } catch (err) {
+    if (signal.aborted) return []
+    throw err
+  }
+
+  const recorded: RecordedFile = {
+    file: mp4File,
+    duration: result.duration,
+    size: result.size,
+  }
+  deps.emitRecord({ phase: "end", ...recorded })
+
+  if (deps.audioNormalizer) await normalize(deps, mp4File)
+
+  deps.emitRecord({
+    phase: "convert",
+    status: "done",
+    input: result.file,
+    output: mp4File,
+  })
+  logger.info(`Converted: ${mp4File}`)
+  deps.setState({ currentFile: mp4File, sessionDuration: result.duration })
+  return [recorded]
+}
+
+async function normalize(deps: RecordingJobDeps, file: string): Promise<void> {
+  if (!deps.audioNormalizer) return
+  deps.emitRecord({ phase: "normalize", status: "start", file })
+  try {
+    const result = await deps.audioNormalizer.normalize(file)
+    deps.emitRecord({
+      phase: "normalize",
+      status: "done",
+      input: file,
+      output: result.output,
+    })
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    deps.emitRecord({
+      phase: "normalize",
+      status: "error",
+      input: file,
+      error: message,
+    })
+  }
+}
+
+function parseSegmentList(
+  listing: string,
+  fallbackDuration: number,
+): { file: string; duration: number }[] {
+  return listing
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .flatMap((line) => {
+      const [file, start, end] = line.split(",").map((field) => field.replace(/^"|"$/g, ""))
+      if (!file) return []
+      const duration = Number(end) - Number(start)
+      return [
+        { file, duration: Number.isFinite(duration) && duration > 0 ? duration : fallbackDuration },
+      ]
+    })
+}

package/src/app/logger.ts

@@ -0,0 +1,133 @@
+/**
+ * Logger — rotating file + console with levels.
+ * Zero-dependency minimal implementation (~60 lines).
+ */
+
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+import type { Logger } from "../core/log"
+import type { LogLevel } from "./config"
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+}
+
+const LEVEL_COLORS: Record<LogLevel, string> = {
+  debug: "\x1b[90m", // gray
+  info: "\x1b[36m", // cyan
+  warn: "\x1b[33m", // yellow
+  error: "\x1b[31m", // red
+}
+
+const RESET = "\x1b[0m"
+
+export function createLogger(opts: {
+  level?: LogLevel
+  logFile?: string
+  maxSize?: number
+  backups?: number
+  /** When true (default), writes to stdout/stderr. Set false for file-only logging. */
+  console?: boolean
+}): Logger {
+  const level = opts.level ?? "info"
+  const logFile = opts.logFile ?? "tiktok-recorder.log"
+  const maxSize = opts.maxSize ?? 5 * 1024 * 1024 // 5 MB
+  const backups = opts.backups ?? 3
+  const showConsole = opts.console !== false // default true
+
+  // Ensure parent directory exists
+  const logDir = dirname(logFile)
+  if (logDir !== ".") {
+    mkdirSync(logDir, { recursive: true })
+  }
+
+  function rotateIfNeeded(): void {
+    try {
+      if (existsSync(logFile)) {
+        const size = statSync(logFile).size
+        if (size >= maxSize) {
+          // Remove the oldest backup
+          const lastBackup = `${logFile}.${backups}`
+          if (existsSync(lastBackup)) {
+            try {
+              renameSync(lastBackup, `${lastBackup}.old`)
+            } catch {
+              // Best-effort cleanup
+            }
+          }
+          // Shift backups
+          for (let i = backups - 1; i >= 1; i--) {
+            const src = `${logFile}.${i}`
+            const dst = `${logFile}.${i + 1}`
+            if (existsSync(src)) {
+              try {
+                renameSync(src, dst)
+              } catch {
+                // Best-effort
+              }
+            }
+          }
+          // Rename current → .1
+          try {
+            renameSync(logFile, `${logFile}.1`)
+          } catch {
+            // Best-effort
+          }
+        }
+      }
+    } catch {
+      // Silent — never throw in logger
+    }
+  }
+
+  // Touch the file
+  try {
+    if (!existsSync(logFile)) {
+      writeFileSync(logFile, "", "utf-8")
+    }
+  } catch {
+    // Best-effort
+  }
+
+  function write(level: LogLevel, msg: string, args: unknown[]): void {
+    const ts = new Date().toISOString()
+    const suffix = args.length > 0 ? ` ${args.map((a) => String(a)).join(" ")}` : ""
+    const line = `[${ts}] [${level.toUpperCase()}] ${msg}${suffix}`
+    const formatted = `[${ts}] [${level.toUpperCase()}] ${msg}${suffix}`
+
+    // Console (optional — can be suppressed for file-only logging)
+    if (showConsole) {
+      if (level === "error") {
+        process.stderr.write(`${LEVEL_COLORS[level]}${formatted}${RESET}\n`)
+      } else {
+        process.stdout.write(`${LEVEL_COLORS[level]}${formatted}${RESET}\n`)
+      }
+    }
+
+    // File
+    try {
+      rotateIfNeeded()
+      appendFileSync(logFile, `${line}\n`, "utf-8")
+    } catch {
+      // Best-effort
+    }
+  }
+
+  return {
+    debug: (msg, ...args) => {
+      if (LEVEL_ORDER.debug >= LEVEL_ORDER[level]) write("debug", msg, args)
+    },
+    info: (msg, ...args) => {
+      if (LEVEL_ORDER.info >= LEVEL_ORDER[level]) write("info", msg, args)
+    },
+    warn: (msg, ...args) => {
+      if (LEVEL_ORDER.warn >= LEVEL_ORDER[level]) write("warn", msg, args)
+    },
+    error: (msg, ...args) => {
+      if (LEVEL_ORDER.error >= LEVEL_ORDER[level]) write("error", msg, args)
+    },
+  }
+}

package/src/app/loop.ts

@@ -0,0 +1,84 @@
+/**
+ * Polling monitor — calls a tick function on a configurable interval.
+ * Fires the first tick immediately, then every N minutes.
+ *
+ * One external `AbortSignal` (the session's AbortScope) interrupts both the
+ * sleep and any in-flight tick; there is no private controller.
+ */
+
+import type { Logger } from "../core/log"
+
+/** Sleep for `ms`, resolving early when `signal` aborts (timer cleared, no orphan). */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve()
+      return
+    }
+    const timer = setTimeout(resolve, ms)
+    if (signal) {
+      signal.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer)
+          resolve()
+        },
+        { once: true },
+      )
+    }
+  })
+}
+
+export interface PollingMonitor {
+  start: () => Promise<void>
+  stop: () => Promise<void>
+  /** Schedule the monitor to stop after the current tick completes. */
+  stopAfterCurrentTick: () => void
+}
+
+export function createPollingMonitor(opts: {
+  intervalMinutes: number
+  signal: AbortSignal
+  onTick: () => Promise<void>
+  logger?: Logger
+}): PollingMonitor {
+  const intervalMs = opts.intervalMinutes * 60 * 1000
+  let currentTick: Promise<void> | null = null
+  let stopAfterTick = false
+
+  async function start(): Promise<void> {
+    opts.logger?.info(`Polling started (interval: ${opts.intervalMinutes} min)`)
+
+    while (!opts.signal.aborted) {
+      currentTick = opts.onTick()
+      try {
+        await currentTick
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        opts.logger?.error(`Tick error: ${msg}`)
+      } finally {
+        currentTick = null
+      }
+
+      if (stopAfterTick || opts.signal.aborted) break
+
+      // Sleep for the full interval — close() aborts the signal to wake us up early
+      await sleep(intervalMs, opts.signal)
+    }
+
+    opts.logger?.info("Polling stopped")
+  }
+
+  async function stop(): Promise<void> {
+    // Wait for in-flight tick to finish; close() only aborts its I/O.
+    if (currentTick) {
+      await currentTick
+    }
+  }
+
+  function stopAfterCurrentTick(): void {
+    stopAfterTick = true
+  }
+
+  return { start, stop, stopAfterCurrentTick }
+}