/** 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;
}
/** 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[];
    };
}