offcourse 1.0.0 → 1.1.0

package/src/downloader/hlsDownloader.test.ts

@@ -1,148 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parseHLSPlaylist, parseHighLevelVideoUrl } from "./hlsDownloader.js";
-
-describe("parseHLSPlaylist", () => {
-  const baseUrl = "https://cdn.example.com/video/";
-
-  it("parses master playlist with multiple qualities", () => {
-    const content = `#EXTM3U
-#EXT-X-VERSION:3
-#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=640x360
-360p.m3u8
-#EXT-X-STREAM-INF:BANDWIDTH=1400000,RESOLUTION=854x480
-480p.m3u8
-#EXT-X-STREAM-INF:BANDWIDTH=2800000,RESOLUTION=1280x720
-720p.m3u8
-#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080
-1080p.m3u8`;
-
-    const result = parseHLSPlaylist(content, baseUrl);
-
-    expect(result).toHaveLength(4);
-    // Should be sorted by bandwidth (highest first)
-    expect(result[0]!.label).toBe("1080p");
-    expect(result[0]!.bandwidth).toBe(5000000);
-    expect(result[0]!.height).toBe(1080);
-    expect(result[0]!.width).toBe(1920);
-    expect(result[0]!.url).toBe("https://cdn.example.com/video/1080p.m3u8");
-
-    expect(result[3]!.label).toBe("360p");
-    expect(result[3]!.bandwidth).toBe(800000);
-  });
-
-  it("handles absolute URLs in playlist", () => {
-    const content = `#EXTM3U
-#EXT-X-STREAM-INF:BANDWIDTH=2800000,RESOLUTION=1280x720
-https://other-cdn.com/video/720p.m3u8`;
-
-    const result = parseHLSPlaylist(content, baseUrl);
-
-    expect(result).toHaveLength(1);
-    expect(result[0]!.url).toBe("https://other-cdn.com/video/720p.m3u8");
-  });
-
-  it("handles playlist without resolution", () => {
-    const content = `#EXTM3U
-#EXT-X-STREAM-INF:BANDWIDTH=500000
-audio.m3u8`;
-
-    const result = parseHLSPlaylist(content, baseUrl);
-
-    expect(result).toHaveLength(1);
-    expect(result[0]!.label).toBe("500k");
-    expect(result[0]!.height).toBeUndefined();
-    expect(result[0]!.width).toBeUndefined();
-  });
-
-  it("handles empty playlist", () => {
-    const content = `#EXTM3U
-#EXT-X-VERSION:3`;
-
-    const result = parseHLSPlaylist(content, baseUrl);
-    expect(result).toHaveLength(0);
-  });
-
-  it("ignores comments and metadata", () => {
-    const content = `#EXTM3U
-#EXT-X-VERSION:3
-# This is a comment
-#EXT-X-INDEPENDENT-SEGMENTS
-#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=1280x720
-720p.m3u8`;
-
-    const result = parseHLSPlaylist(content, baseUrl);
-    expect(result).toHaveLength(1);
-  });
-
-  it("handles real-world Vimeo-style playlist", () => {
-    const content = `#EXTM3U
-#EXT-X-VERSION:4
-#EXT-X-STREAM-INF:AVERAGE-BANDWIDTH=246064,BANDWIDTH=326400,CODECS="avc1.4D401E,mp4a.40.2",RESOLUTION=426x240,FRAME-RATE=24.000
-https://vod.example.com/exp=123/~hmac=abc/240p/prog_index.m3u8
-#EXT-X-STREAM-INF:AVERAGE-BANDWIDTH=602416,BANDWIDTH=796800,CODECS="avc1.4D401F,mp4a.40.2",RESOLUTION=640x360,FRAME-RATE=24.000
-https://vod.example.com/exp=123/~hmac=abc/360p/prog_index.m3u8
-#EXT-X-STREAM-INF:AVERAGE-BANDWIDTH=1270416,BANDWIDTH=1680000,CODECS="avc1.4D401F,mp4a.40.2",RESOLUTION=854x480,FRAME-RATE=24.000
-https://vod.example.com/exp=123/~hmac=abc/480p/prog_index.m3u8`;
-
-    const result = parseHLSPlaylist(content, baseUrl);
-
-    expect(result).toHaveLength(3);
-    expect(result[0]!.height).toBe(480);
-    expect(result[1]!.height).toBe(360);
-    expect(result[2]!.height).toBe(240);
-  });
-});
-
-describe("parseHighLevelVideoUrl", () => {
-  it("parses standard HighLevel HLS URL", () => {
-    const url =
-      "https://backend.leadconnectorhq.com/hls/v2/memberships/ABC123/videos/video-id-456/master.m3u8";
-
-    const result = parseHighLevelVideoUrl(url);
-
-    expect(result).toEqual({
-      locationId: "ABC123",
-      videoId: "video-id-456",
-    });
-  });
-
-  it("parses URL with token", () => {
-    const url =
-      "https://backend.leadconnectorhq.com/hls/v2/memberships/LOC123/videos/VID456/master.m3u8?token=secret-token";
-
-    const result = parseHighLevelVideoUrl(url);
-
-    expect(result).toEqual({
-      locationId: "LOC123",
-      videoId: "VID456",
-      token: "secret-token",
-    });
-  });
-
-  it("handles complex video IDs", () => {
-    const url =
-      "https://cdn.example.com/hls/memberships/location-abc/videos/cts-184162b5f0747fcd,1080p/master.m3u8";
-
-    const result = parseHighLevelVideoUrl(url);
-
-    expect(result).toEqual({
-      locationId: "location-abc",
-      videoId: "cts-184162b5f0747fcd",
-    });
-  });
-
-  it("returns null for non-HighLevel URLs", () => {
-    expect(parseHighLevelVideoUrl("https://vimeo.com/123456")).toBeNull();
-    expect(parseHighLevelVideoUrl("https://youtube.com/watch?v=abc")).toBeNull();
-  });
-
-  it("returns null for invalid URLs", () => {
-    expect(parseHighLevelVideoUrl("not-a-url")).toBeNull();
-    expect(parseHighLevelVideoUrl("")).toBeNull();
-  });
-
-  it("returns null for missing video path", () => {
-    const url = "https://backend.leadconnectorhq.com/hls/v2/other/path";
-    expect(parseHighLevelVideoUrl(url)).toBeNull();
-  });
-});

package/src/downloader/hlsDownloader.ts

@@ -1,327 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { execa } from "execa";
-import * as HLS from "hls-parser";
-import type { DownloadProgress } from "./loomDownloader.js";
-
-export interface HLSDownloadResult {
-  success: boolean;
-  error?: string;
-  errorCode?: string;
-  outputPath?: string;
-  duration?: number;
-}
-
-export interface HLSQuality {
-  label: string;
-  url: string;
-  bandwidth: number;
-  width?: number | undefined;
-  height?: number | undefined;
-}
-
-/**
- * Checks if ffmpeg is available on the system.
- */
-/* v8 ignore next 8 */
-export async function checkFfmpeg(): Promise<boolean> {
-  try {
-    await execa("ffmpeg", ["-version"]);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Fetches an HLS master playlist and parses quality variants.
- */
-/* v8 ignore next 14 */
-export async function fetchHLSQualities(masterUrl: string): Promise<HLSQuality[]> {
-  try {
-    const response = await fetch(masterUrl);
-    if (!response.ok) {
-      throw new Error(`Failed to fetch playlist: ${response.status}`);
-    }
-
-    const content = await response.text();
-    return parseHLSPlaylist(content, masterUrl);
-  } catch (error) {
-    console.error("Failed to fetch HLS qualities:", error);
-    return [];
-  }
-}
-
-/**
- * Parses an HLS master playlist to extract quality variants.
- * Uses hls-parser for robust parsing.
- */
-export function parseHLSPlaylist(content: string, baseUrl: string): HLSQuality[] {
-  try {
-    const playlist = HLS.parse(content);
-
-    // Check if it's a master playlist with variants
-    if (!("variants" in playlist) || !playlist.variants) {
-      return [];
-    }
-
-    const variants: HLSQuality[] = playlist.variants.map((variant) => {
-      const bandwidth = variant.bandwidth ?? 0;
-      const resolution = variant.resolution;
-      const width = resolution?.width;
-      const height = resolution?.height;
-
-      // Build absolute URL
-      const variantUrl = variant.uri.startsWith("http")
-        ? variant.uri
-        : new URL(variant.uri, baseUrl).href;
-
-      const label = height ? `${height}p` : `${Math.round(bandwidth / 1000)}k`;
-
-      return {
-        label,
-        url: variantUrl,
-        bandwidth,
-        width,
-        height,
-      };
-    });
-
-    // Sort by bandwidth (highest first)
-    variants.sort((a, b) => b.bandwidth - a.bandwidth);
-
-    return variants;
-  } catch {
-    // Fallback to empty array on parse error
-    return [];
-  }
-}
-
-/**
- * Gets the best quality URL from a master playlist.
- * @param masterUrl The master playlist URL
- * @param preferredHeight Preferred video height (e.g., 720, 1080)
- */
-/* v8 ignore start */
-export async function getBestQualityUrl(
-  masterUrl: string,
-  preferredHeight?: number
-): Promise<string> {
-  const qualities = await fetchHLSQualities(masterUrl);
-
-  if (qualities.length === 0) {
-    // Assume it's a direct media playlist
-    return masterUrl;
-  }
-
-  if (preferredHeight) {
-    // Find closest match to preferred height
-    const match = qualities.find((q) => q.height === preferredHeight);
-    if (match) return match.url;
-
-    // Find closest lower quality
-    const lower = qualities.filter((q) => q.height && q.height <= preferredHeight);
-    const closest = lower[0];
-    if (closest) {
-      return closest.url;
-    }
-  }
-
-  // Return highest quality
-  return qualities[0]?.url ?? masterUrl;
-}
-
-/**
- * Downloads an HLS stream using ffmpeg.
- * @param hlsUrl The HLS playlist URL (master or media)
- * @param outputPath The output file path (should end in .mp4)
- * @param onProgress Progress callback
- */
-export async function downloadHLSVideo(
-  hlsUrl: string,
-  outputPath: string,
-  onProgress?: (progress: DownloadProgress) => void
-): Promise<HLSDownloadResult> {
-  // Check if ffmpeg is available
-  const hasFfmpeg = await checkFfmpeg();
-  if (!hasFfmpeg) {
-    return {
-      success: false,
-      error: "ffmpeg is not installed. Please install ffmpeg to download HLS videos.",
-      errorCode: "FFMPEG_NOT_FOUND",
-    };
-  }
-
-  // Ensure output directory exists
-  const outputDir = path.dirname(outputPath);
-  if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
-  }
-
-  // Build ffmpeg command
-  const args = [
-    "-y", // Overwrite output
-    "-hide_banner",
-    "-loglevel",
-    "warning",
-    "-stats",
-    "-i",
-    hlsUrl,
-    "-c",
-    "copy", // Copy streams without re-encoding
-    "-bsf:a",
-    "aac_adtstoasc", // Fix AAC stream
-    outputPath,
-  ];
-
-  let duration = 0;
-  let currentTime = 0;
-  let lastProgressUpdate = 0;
-
-  const updateProgress = () => {
-    if (duration > 0 && onProgress) {
-      const percent = Math.min((currentTime / duration) * 100, 100);
-      const now = Date.now();
-
-      // Throttle progress updates to avoid spam
-      if (now - lastProgressUpdate > 200 || percent >= 100) {
-        lastProgressUpdate = now;
-        onProgress({
-          phase: "downloading",
-          percent: Math.round(percent),
-          currentBytes: currentTime,
-          totalBytes: duration,
-        });
-      }
-    }
-  };
-
-  try {
-    const subprocess = execa("ffmpeg", args);
-
-    // Parse stderr for progress info
-    subprocess.stderr?.on("data", (data: Buffer) => {
-      const output = data.toString();
-
-      // Parse duration from input info
-      const durationMatch = /Duration:\s*(\d{2}):(\d{2}):(\d{2})\.(\d{2})/.exec(output);
-      if (durationMatch && duration === 0) {
-        const [, hours = "0", mins = "0", secs = "0", centis = "0"] = durationMatch;
-        duration =
-          parseInt(hours, 10) * 3600 +
-          parseInt(mins, 10) * 60 +
-          parseInt(secs, 10) +
-          parseInt(centis, 10) / 100;
-      }
-
-      // Parse current time from progress
-      const timeMatch = /time=(\d{2}):(\d{2}):(\d{2})\.(\d{2})/.exec(output);
-      if (timeMatch) {
-        const [, hours = "0", mins = "0", secs = "0", centis = "0"] = timeMatch;
-        currentTime =
-          parseInt(hours, 10) * 3600 +
-          parseInt(mins, 10) * 60 +
-          parseInt(secs, 10) +
-          parseInt(centis, 10) / 100;
-
-        updateProgress();
-      }
-    });
-
-    await subprocess;
-
-    // Final progress update
-    if (onProgress) {
-      onProgress({
-        phase: "complete",
-        percent: 100,
-      });
-    }
-
-    return {
-      success: true,
-      outputPath,
-      duration,
-    };
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    return {
-      success: false,
-      error: `ffmpeg error: ${errorMessage}`,
-      errorCode: "FFMPEG_ERROR",
-    };
-  }
-}
-
-/**
- * Downloads a HighLevel HLS video with quality selection.
- * @param masterUrl The master playlist URL (may include token)
- * @param outputPath The output file path
- * @param preferredQuality Preferred quality label (e.g., "720p", "1080p")
- * @param onProgress Progress callback
- */
-export async function downloadHighLevelVideo(
-  masterUrl: string,
-  outputPath: string,
-  preferredQuality?: string,
-  onProgress?: (progress: DownloadProgress) => void
-): Promise<HLSDownloadResult> {
-  // Report start
-  onProgress?.({
-    phase: "preparing",
-    percent: 0,
-  });
-
-  // Parse preferred height from quality string
-  let preferredHeight: number | undefined;
-  if (preferredQuality) {
-    const match = /(\d+)p?/i.exec(preferredQuality);
-    if (match?.[1]) {
-      preferredHeight = parseInt(match[1], 10);
-    }
-  }
-
-  // Get the best quality URL
-  let downloadUrl = masterUrl;
-  try {
-    downloadUrl = await getBestQualityUrl(masterUrl, preferredHeight);
-  } catch (error) {
-    console.warn("Failed to fetch quality options, using master URL:", error);
-  }
-
-  // Download using ffmpeg
-  return downloadHLSVideo(downloadUrl, outputPath, onProgress);
-}
-/* v8 ignore stop */
-
-/**
- * Extracts video info from a HighLevel HLS URL.
- */
-export function parseHighLevelVideoUrl(url: string): {
-  locationId: string;
-  videoId: string;
-  token?: string | undefined;
-} | null {
-  try {
-    const urlObj = new URL(url);
-
-    // Pattern: /hls/v2/memberships/{locationId}/videos/{videoId}/...
-    const match = /\/memberships\/([^/]+)\/videos\/([^/,]+)/.exec(urlObj.pathname);
-    const locationId = match?.[1];
-    const videoId = match?.[2];
-
-    if (!locationId || !videoId) {
-      return null;
-    }
-
-    const token = urlObj.searchParams.get("token");
-
-    return {
-      locationId,
-      videoId,
-      ...(token ? { token } : {}),
-    };
-  } catch {
-    return null;
-  }
-}

package/src/downloader/hlsValidator.ts

@@ -1,196 +0,0 @@
-/**
- * HLS stream validation - requires network access to verify streams.
- * Excluded from coverage via vitest.config.ts.
- */
-import { extractLoomId, getLoomVideoInfoDetailed } from "./loomDownloader.js";
-import {
-  extractVimeoId,
-  getVimeoVideoInfo,
-  getVimeoVideoInfoFromBrowser,
-} from "./vimeoDownloader.js";
-import { captureLoomHls, captureVimeoConfig } from "../scraper/videoInterceptor.js";
-import type { Page } from "playwright";
-
-/**
- * Result of HLS validation.
- */
-export interface HlsValidationResult {
-  isValid: boolean;
-  hlsUrl: string | null;
-  error?: string;
-  errorCode?: string;
-  details?: string;
-}
-
-/**
- * Validates that a Loom video has an accessible HLS stream.
- * This should be called during the scanning phase to catch issues early.
- *
- * @param loomUrl - The Loom video URL
- * @param page - Optional Playwright page for network interception fallback
- */
-export async function validateLoomHls(loomUrl: string, page?: Page): Promise<HlsValidationResult> {
-  const videoId = extractLoomId(loomUrl);
-
-  if (!videoId) {
-    return {
-      isValid: false,
-      hlsUrl: null,
-      error: "Invalid Loom URL - could not extract video ID",
-      errorCode: "INVALID_URL",
-      details: `URL: ${loomUrl}`,
-    };
-  }
-
-  // First try direct API
-  const result = await getLoomVideoInfoDetailed(videoId, 2, 500);
-
-  if (result.success && result.info) {
-    return {
-      isValid: true,
-      hlsUrl: result.info.hlsUrl,
-    };
-  }
-
-  // If direct API failed and we have a page, try network interception
-  if (page && result.errorCode === "HLS_NOT_FOUND") {
-    const captured = await captureLoomHls(page, videoId, 15000);
-    if (captured.hlsUrl) {
-      return {
-        isValid: true,
-        hlsUrl: captured.hlsUrl,
-        details: "Captured via network interception",
-      };
-    }
-  }
-
-  // Return the original error
-  const validation: HlsValidationResult = {
-    isValid: false,
-    hlsUrl: null,
-    error: result.error ?? "Failed to fetch Loom video info",
-  };
-  if (result.errorCode) {
-    validation.errorCode = result.errorCode;
-  }
-  if (result.details) {
-    validation.details = result.details;
-  }
-  return validation;
-}
-
-/**
- * Validates a Vimeo video has accessible streams.
- * @param vimeoUrl - The Vimeo video URL
- * @param page - Optional Playwright page for domain-restricted videos
- * @param lessonUrl - Optional lesson URL for referer-based access
- */
-export async function validateVimeoVideo(
-  vimeoUrl: string,
-  page?: Page,
-  lessonUrl?: string
-): Promise<HlsValidationResult> {
-  const videoId = extractVimeoId(vimeoUrl);
-
-  if (!videoId) {
-    return {
-      isValid: false,
-      hlsUrl: null,
-      error: "Invalid Vimeo URL - could not extract video ID",
-      errorCode: "INVALID_URL",
-      details: `URL: ${vimeoUrl}`,
-    };
-  }
-
-  // Extract unlisted hash if present
-  const hashMatch =
-    /vimeo\.com\/\d+\/([a-f0-9]+)/.exec(vimeoUrl) ?? /[?&]h=([a-f0-9]+)/.exec(vimeoUrl);
-  const unlistedHash = hashMatch?.[1] ?? null;
-
-  // First try direct fetch (works for public videos)
-  let result = await getVimeoVideoInfo(videoId, unlistedHash, lessonUrl);
-
-  // If video is private/restricted and we have a browser context, try browser-based fetch
-  if (!result.success && result.errorCode === "PRIVATE_VIDEO" && page) {
-    result = await getVimeoVideoInfoFromBrowser(page, videoId, unlistedHash);
-  }
-
-  // If still failing and we have a page, try extracting from the running player
-  if (!result.success && result.errorCode === "PRIVATE_VIDEO" && page) {
-    const captured = await captureVimeoConfig(page, videoId, 20000);
-    if (captured.hlsUrl || captured.progressiveUrl) {
-      return {
-        isValid: true,
-        hlsUrl: captured.hlsUrl ?? captured.progressiveUrl,
-        details: "Extracted from running player",
-      };
-    }
-  }
-
-  if (!result.success || !result.info) {
-    const validation: HlsValidationResult = {
-      isValid: false,
-      hlsUrl: null,
-      error: result.error ?? "Failed to fetch Vimeo video info",
-    };
-    if (result.errorCode) {
-      validation.errorCode = result.errorCode;
-    }
-    if (result.details) {
-      validation.details = result.details;
-    }
-    return validation;
-  }
-
-  // Return HLS URL if available, or progressive URL as fallback
-  return {
-    isValid: true,
-    hlsUrl: result.info.hlsUrl ?? result.info.progressiveUrl,
-  };
-}
-
-/**
- * Validates HLS availability for a video URL based on its type.
- * @param videoUrl - The video URL to validate
- * @param videoType - The type of video (loom, vimeo, etc.)
- * @param page - Optional Playwright page for network interception fallback
- * @param lessonUrl - Optional lesson URL for referer-based access
- */
-export async function validateVideoHls(
-  videoUrl: string,
-  videoType: string,
-  page?: Page,
-  lessonUrl?: string
-): Promise<HlsValidationResult> {
-  switch (videoType) {
-    case "loom":
-      return validateLoomHls(videoUrl, page);
-
-    case "vimeo":
-      return validateVimeoVideo(videoUrl, page, lessonUrl);
-
-    case "youtube":
-    case "wistia":
-      // These require yt-dlp - skip validation, will fail at download
-      return {
-        isValid: true,
-        hlsUrl: null,
-        details: `${videoType} requires yt-dlp - will attempt download`,
-      };
-
-    case "native":
-      // Native videos have direct URLs, no HLS needed
-      return {
-        isValid: true,
-        hlsUrl: videoUrl,
-      };
-
-    default:
-      return {
-        isValid: false,
-        hlsUrl: null,
-        error: `Unknown video type: ${videoType}`,
-        errorCode: "UNKNOWN_TYPE",
-      };
-  }
-}