youtube-transcript-plus 1.2.0 → 2.0.0

package/dist/types.d.ts

@@ -1,28 +1,152 @@
+/** Interface for implementing custom caching strategies. */
 export interface CacheStrategy {
+    /** Retrieve a cached value by key. Returns `null` if not found or expired. */
     get(key: string): Promise<string | null>;
+    /** Store a value in the cache with an optional TTL in milliseconds. */
     set(key: string, value: string, ttl?: number): Promise<void>;
 }
+/** Parameters passed to custom fetch functions (`videoFetch`, `playerFetch`, `transcriptFetch`). */
 export interface FetchParams {
+    /** The URL to fetch. */
     url: string;
+    /** The requested language code (e.g., `'en'`, `'fr'`). */
     lang?: string;
+    /** The User-Agent string for the request. */
     userAgent?: string;
+    /** HTTP method — `'GET'` for watch/transcript pages, `'POST'` for the Innertube player endpoint. */
     method?: 'GET' | 'POST';
+    /** Request body (only present for POST requests). */
     body?: string;
+    /** Additional HTTP headers (e.g., `Content-Type` for the player endpoint). */
     headers?: Record<string, string>;
+    /** AbortSignal to cancel the request. */
+    signal?: AbortSignal;
 }
+/** Configuration options for fetching transcripts. */
 export interface TranscriptConfig {
+    /** BCP 47 language code for the transcript (e.g., `'en'`, `'fr'`). */
     lang?: string;
+    /** Custom User-Agent string for HTTP requests. */
     userAgent?: string;
+    /** Custom caching strategy implementing the {@link CacheStrategy} interface. */
     cache?: CacheStrategy;
+    /** Time-to-live for cache entries in milliseconds. Defaults to 1 hour. */
     cacheTTL?: number;
+    /** Use HTTP instead of HTTPS for YouTube requests. Not recommended for production. */
     disableHttps?: boolean;
+    /** Custom fetch function for the YouTube watch page (GET request). */
     videoFetch?: (params: FetchParams) => Promise<Response>;
+    /** Custom fetch function for the transcript XML data (GET request). */
     transcriptFetch?: (params: FetchParams) => Promise<Response>;
+    /** Custom fetch function for the YouTube Innertube player API (POST request). */
     playerFetch?: (params: FetchParams) => Promise<Response>;
+    /** Maximum number of retry attempts for transient failures (429, 5xx). Defaults to `0` (no retries). */
+    retries?: number;
+    /** Base delay in milliseconds for exponential backoff between retries. Defaults to `1000`. */
+    retryDelay?: number;
+    /** AbortSignal to cancel in-flight requests. */
+    signal?: AbortSignal;
+    /** When `true`, return a {@link TranscriptResult} containing both video details and segments. */
+    videoDetails?: boolean;
 }
-export interface TranscriptResponse {
+/** A single transcript segment returned by {@link fetchTranscript}. */
+export interface TranscriptSegment {
+    /** The text content of the transcript segment. */
     text: string;
+    /** Duration of the segment in seconds. */
     duration: number;
+    /** Start time of the segment in seconds from the beginning of the video. */
     offset: number;
+    /** The language code of the transcript. */
     lang: string;
 }
+/**
+ * @deprecated Use {@link TranscriptSegment} instead.
+ */
+export type TranscriptResponse = TranscriptSegment;
+/** A video thumbnail image. */
+export interface Thumbnail {
+    /** URL of the thumbnail image. */
+    url: string;
+    /** Width of the thumbnail in pixels. */
+    width: number;
+    /** Height of the thumbnail in pixels. */
+    height: number;
+}
+/** Metadata about a YouTube video, extracted from the Innertube player response. */
+export interface VideoDetails {
+    /** The video's unique ID. */
+    videoId: string;
+    /** Video title. */
+    title: string;
+    /** Channel/uploader name. */
+    author: string;
+    /** Uploader's channel ID. */
+    channelId: string;
+    /** Duration in seconds. */
+    lengthSeconds: number;
+    /** Number of views. */
+    viewCount: number;
+    /** Video description. */
+    description: string;
+    /** Array of keyword tags. */
+    keywords: string[];
+    /** Array of thumbnail images at various resolutions. */
+    thumbnails: Thumbnail[];
+    /** Whether the video is live content. */
+    isLiveContent: boolean;
+}
+/** Result returned by {@link fetchTranscript} when `videoDetails: true` is set. */
+export interface TranscriptResult {
+    /** Metadata about the video. */
+    videoDetails: VideoDetails;
+    /** Array of transcript segments. */
+    segments: TranscriptSegment[];
+}
+/** Shape of a single caption track from the Innertube player response. */
+export interface CaptionTrack {
+    baseUrl?: string;
+    url?: string;
+    languageCode: string;
+    name?: {
+        simpleText?: string;
+    };
+    kind?: string;
+}
+/** Information about an available caption track for a video. */
+export interface CaptionTrackInfo {
+    /** BCP 47 language code (e.g., `'en'`, `'fr'`, `'pt-BR'`). */
+    languageCode: string;
+    /** Human-readable language name (e.g., `'English'`, `'French'`). */
+    languageName: string;
+    /** Whether the captions are auto-generated by YouTube's speech recognition. */
+    isAutoGenerated: boolean;
+}
+/** Shape of the Innertube player JSON response (relevant subset). */
+export interface InnertubePlayerResponse {
+    playabilityStatus?: {
+        status?: string;
+    };
+    videoDetails?: {
+        videoId?: string;
+        title?: string;
+        author?: string;
+        channelId?: string;
+        lengthSeconds?: string;
+        viewCount?: string;
+        shortDescription?: string;
+        keywords?: string[];
+        thumbnail?: {
+            thumbnails?: Thumbnail[];
+        };
+        isLiveContent?: boolean;
+    };
+    captions?: {
+        playerCaptionsTracklistRenderer?: {
+            captionTracks?: CaptionTrack[];
+        };
+    };
+    playerCaptionsTracklistRenderer?: {
+        captionTracks?: CaptionTrack[];
+    };
+}

package/dist/utils.d.ts

@@ -1,4 +1,24 @@
 import { FetchParams } from './types';
 export declare function decodeXmlEntities(text: string): string;
 export declare function retrieveVideoId(videoId: string): string;
+/**
+ * Validate that a language code matches a BCP 47-like pattern.
+ * @throws {@link YoutubeTranscriptInvalidLangError} if the language code is invalid.
+ */
+export declare function validateLang(lang: string): void;
 export declare function defaultFetch(params: FetchParams): Promise<Response>;
+/** Returns true if the HTTP status code is retryable (429 or 5xx). */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * Wrap a fetch call with retry logic using exponential backoff.
+ *
+ * Retries on 429 (Too Many Requests) and 5xx (Server Errors).
+ * Client errors (4xx other than 429) are returned immediately.
+ *
+ * @param fetchFn - Function that performs the fetch call.
+ * @param retries - Maximum number of retry attempts (0 = no retries).
+ * @param retryDelay - Base delay in milliseconds for exponential backoff.
+ * @param signal - Optional AbortSignal to cancel the operation.
+ * @returns The fetch Response.
+ */
+export declare function fetchWithRetry(fetchFn: () => Promise<Response>, retries: number, retryDelay: number, signal?: AbortSignal): Promise<Response>;