tubezero 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -1,89 +1,3 @@
-/**
- * scraper.ts
- * Scrapes user-specific YouTube feeds: History, Likes, Watch Later, and Custom Playlists.
- * Works client-side (Chrome extensions, desktop apps, or CORS-proxied environments).
- */
-interface VideoEntry {
-    title: string;
-    channel: string;
-}
-interface InnerTubeConfig {
-    apiKey: string | null;
-    clientVersion: string;
-    idToken: string | null;
-}
-interface CustomPlaylist {
-    url: string;
-}
-interface CustomPlaylistData {
-    id: string;
-    entries: VideoEntry[];
-}
-interface TasteData {
-    historyEntries: VideoEntry[];
-    likesEntries: VideoEntry[];
-    wlEntries: VideoEntry[];
-    dislikesEntries: VideoEntry[];
-    customPlaylistsData: CustomPlaylistData[];
-}
-/**
- * Fetches the HTML of a YouTube page and extracts `ytInitialData`.
- * @param url - The URL to fetch.
- * @returns The parsed ytInitialData object or null.
- */
-declare function fetchYtInitialData(url: string): Promise<any>;
-/**
- * Reads SAPISID cookies from the browser environment.
- * Only works if running on a youtube.com domain or in an extension with cookie access.
- * @returns The SAPISID value or null.
- */
-declare function getSapisidFromCookie(): string | null;
-/**
- * Generates the SAPISIDHASH Authorization header value needed for authenticated InnerTube requests.
- * @param sapisid - The SAPISID cookie value.
- * @param origin - The request origin.
- * @returns The generated authorization hash or null.
- */
-declare function getSApiSidHash(sapisid: string, origin?: string): Promise<string | null>;
-/**
- * Recursively scans a JSON object to extract video entries { title, channel }.
- * Handles both the legacy videoRenderer and the newer lockupViewModel schemas.
- * @param data - The JSON object to search.
- * @returns Array of extracted video entries.
- */
-declare function extractVideoEntries(data: any): VideoEntry[];
-/**
- * Extracts InnerTube credentials and configuration parameters by parsing the YouTube home page.
- * @param injectedConfig - Pre-fetched config if available (bypasses fetching).
- * @returns InnerTube config parameters.
- */
-declare function getInnerTubeConfig(injectedConfig?: Partial<InnerTubeConfig> | null): Promise<InnerTubeConfig>;
-/**
- * Recursively searches for the continuation token in an InnerTube response.
- * @param obj - InnerTube response subtree.
- * @returns The token or null.
- */
-declare function findContinuationToken(obj: any): string | null;
-/**
- * Fetches video list from a specific InnerTube browse ID, paginating if needed.
- * @param apiKey - InnerTube API Key.
- * @param clientVersion - InnerTube client version string.
- * @param idToken - Identity Token.
- * @param browseId - Target feed ID (e.g. 'FEhistory', 'VLLL', 'VLWL').
- * @param limit - Maximum entries to fetch.
- * @returns Array of videos.
- */
-declare function fetchInnerTubeFeed(apiKey: string, clientVersion: string, idToken: string | null, browseId: string, limit?: number): Promise<VideoEntry[]>;
-/**
- * Scrapes History, Liked videos, Watch Later, and any custom playlists.
- * Tries the InnerTube JSON API first, then falls back to HTML-scraping + paginating if needed.
- * @param injectedConfig - Preconfigured InnerTube parameters.
- * @param customPlaylists - Custom playlist definitions with URLs/IDs.
- * @param limit - Maximum items to retrieve per feed.
- * @returns Scraped feeds.
- */
-declare function scrapeTasteData(injectedConfig?: Partial<InnerTubeConfig> | null, customPlaylists?: CustomPlaylist[], limit?: number): Promise<TasteData>;
-
 declare class Base {
     client: Client;
     constructor(client: Client);
@@ -105,10 +19,11 @@ interface Thumbnail {
     width: number;
     height: number;
 }
-declare class Thumbnails {
-    list: Thumbnail[];
-    constructor(list: Thumbnail[]);
-    getBestResolution(): Thumbnail | undefined;
+declare class Thumbnails extends Array<Thumbnail> {
+    constructor(list?: Thumbnail[] | number);
+    get min(): string | undefined;
+    get best(): string | undefined;
+    load(thumbnails: Thumbnail[]): Thumbnails;
 }
 
 interface ChannelInfo {
@@ -157,21 +72,208 @@ declare class SearchResult extends Continuable<SearchItem> {
     private static parseData;
 }
 
+declare class ChannelVideos extends Continuable<VideoCompact> {
+    channel: BaseChannel;
+    constructor(client: Client, channel: BaseChannel);
+    protected fetch(): Promise<{
+        items: VideoCompact[];
+        continuation?: string | null;
+    }>;
+}
+declare class ChannelShorts extends Continuable<VideoCompact> {
+    channel: BaseChannel;
+    constructor(client: Client, channel: BaseChannel);
+    protected fetch(): Promise<{
+        items: VideoCompact[];
+        continuation?: string | null;
+    }>;
+}
+declare class ChannelLive extends Continuable<VideoCompact> {
+    channel: BaseChannel;
+    constructor(client: Client, channel: BaseChannel);
+    protected fetch(): Promise<{
+        items: VideoCompact[];
+        continuation?: string | null;
+    }>;
+}
+declare class ChannelPlaylists extends Continuable<PlaylistCompact> {
+    channel: BaseChannel;
+    constructor(client: Client, channel: BaseChannel);
+    protected fetch(): Promise<{
+        items: PlaylistCompact[];
+        continuation?: string | null;
+    }>;
+}
+declare class ChannelPosts extends Continuable<any> {
+    channel: BaseChannel;
+    constructor(client: Client, channel: BaseChannel);
+    protected fetch(): Promise<{
+        items: any[];
+        continuation?: string | null;
+    }>;
+}
+declare class BaseChannel extends Base {
+    id: string;
+    name: string;
+    handle?: string;
+    description?: string;
+    thumbnails?: Thumbnails;
+    subscriberCount?: string;
+    videos: ChannelVideos;
+    shorts: ChannelShorts;
+    live: ChannelLive;
+    playlists: ChannelPlaylists;
+    posts: ChannelPosts;
+    constructor(client: Client, data?: any);
+    get url(): string;
+    load(data: any): BaseChannel;
+}
+
+declare class VideoRelated extends Continuable<VideoCompact | PlaylistCompact> {
+    video: Video;
+    constructor(client: Client, video: Video);
+    protected fetch(): Promise<{
+        items: (VideoCompact | PlaylistCompact)[];
+        continuation?: string | null;
+    }>;
+}
+
+interface CaptionSegment {
+    utf8: string;
+    tOffsetMs?: number;
+    acpText?: string;
+}
+declare class CaptionLanguage {
+    captions: VideoCaptions;
+    name: string;
+    code: string;
+    isTranslatable: boolean;
+    url: string;
+    constructor(attr: {
+        captions: VideoCaptions;
+        name: string;
+        code: string;
+        isTranslatable: boolean;
+        url: string;
+    });
+    get(translationLanguageCode?: string): Promise<Caption[] | undefined>;
+}
+declare class Caption {
+    duration: number;
+    start: number;
+    text: string;
+    segments?: CaptionSegment[];
+    constructor(attr: Partial<Caption>);
+    get end(): number;
+}
+
+declare class VideoCaptions extends Base {
+    video: Video;
+    languages: CaptionLanguage[];
+    constructor(attr: {
+        video: Video;
+        client: Client;
+    });
+    load(data: any): VideoCaptions;
+    get(languageCode?: string, translationLanguageCode?: string): Promise<Caption[] | undefined>;
+}
+
+interface Format {
+    itag: number;
+    url: string;
+    mimeType: string;
+    bitrate: number;
+    width?: number;
+    height?: number;
+    hasVideo: boolean;
+    hasAudio: boolean;
+    isLive: boolean;
+    contentLength?: string;
+    quality?: string;
+    qualityLabel?: string;
+    audioQuality?: string;
+    approxDurationMs?: string;
+}
+interface StreamingData {
+    expiresInSeconds: string;
+    formats: Format[];
+    adaptiveFormats: Format[];
+}
 declare class BaseVideo extends Base {
     id: string;
     title: string;
     description: string;
     thumbnails: Thumbnails;
     viewCount: number | null;
-    publishDate: string | null;
-    channel?: ChannelInfo;
-    isLive: boolean;
-    constructor(client: Client, data: any);
+    uploadDate: string | null;
+    channel: BaseChannel | null;
+    channels: BaseChannel[] | null;
+    isLiveContent: boolean;
+    likeCount: number | null;
+    tags: string[];
+    formats: any[];
+    adaptiveFormats: any[];
+    streamingData?: StreamingData;
+    related: VideoRelated;
+    captions: VideoCaptions | null;
+    constructor(client: Client, data?: any);
     protected parse(data: any): void;
+    get upNext(): any;
 }
 
+declare class CommentReplies extends Continuable<Comment> {
+    comment: Comment;
+    constructor(client: Client, comment: Comment);
+    protected fetch(): Promise<{
+        items: Comment[];
+        continuation?: string | null;
+    }>;
+}
+declare class VideoComments extends Continuable<Comment> {
+    video: Video;
+    constructor(client: Client, video: Video);
+    protected fetch(): Promise<{
+        items: Comment[];
+        continuation?: string | null;
+    }>;
+}
+declare class Comment extends Base {
+    id: string;
+    video: Video;
+    author: BaseChannel;
+    content: string;
+    publishDate: string;
+    likeCount: number;
+    isAuthorChannelOwner: boolean;
+    isPinned: boolean;
+    replyCount: number;
+    replies: CommentReplies;
+    constructor(client: Client, options: {
+        payload: any;
+        video: Video;
+    });
+    load(payload: any): Comment;
+    get url(): string;
+}
+
+interface Chapter {
+    title: string;
+    start: number;
+    thumbnails: Thumbnails;
+}
+interface MusicMetadata {
+    imageUrl: string;
+    title: string;
+    artist: string;
+    album?: string | null;
+}
 declare class Video extends BaseVideo {
+    duration: number;
+    chapters: Chapter[];
+    comments: VideoComments;
+    music: MusicMetadata | null;
     constructor(client: Client, data: any);
+    load(data: any): Video;
 }
 
 declare class PlaylistVideos extends Continuable<VideoCompact> {
@@ -194,87 +296,182 @@ declare class Playlist extends Base {
     private parse;
 }
 
+interface ChannelShelf {
+    title: string;
+    subtitle?: string;
+    items: any[];
+}
+declare class Channel extends BaseChannel {
+    videoCount?: string;
+    banner: Thumbnails;
+    mobileBanner: Thumbnails;
+    tvBanner: Thumbnails;
+    shelves: ChannelShelf[];
+    constructor(client: Client, data?: any);
+    load(data: any): Channel;
+}
+
+declare class MixPlaylist extends Base {
+    id: string;
+    title: string;
+    videoCount: number;
+    videos: VideoCompact[];
+    constructor(client: Client, data?: any);
+    load(data: any): MixPlaylist;
+}
+
+declare class LiveVideo extends BaseVideo {
+    watchingCount: number;
+    chatContinuation: string;
+    private delay;
+    private chatRequestPoolingTimeout;
+    private timeoutMs;
+    private isChatPlaying;
+    private chatQueue;
+    private pollSessionId;
+    private listeners;
+    constructor(client: Client, data?: any);
+    on(event: string, listener: Function): this;
+    emit(event: string, ...args: any[]): boolean;
+    load(data: any): LiveVideo;
+    playChat(delay?: number): void;
+    stopChat(): void;
+    private pollChatContinuation;
+}
+
 /**
  * client.ts
  * Core InnerTube Client class for TubeVanilla.
  * Optimized for client-side environments with zero external dependencies.
  */
 
+interface InnerTubeConfig {
+    apiKey: string | null;
+    clientVersion: string;
+    idToken: string | null;
+}
+interface Cache {
+    get(key: string): Promise<any> | any;
+    set(key: string, value: any): Promise<void> | void;
+}
 interface ClientOptions {
     apiKey?: string | null;
     clientVersion?: string;
     idToken?: string | null;
     cookie?: string;
+    fetch?: typeof globalThis.fetch;
+    cache?: Cache;
 }
+interface ClientProfile {
+    name: string;
+    clientName: string;
+    clientVersion: string;
+    clientNameHeader: string;
+    userAgent: string;
+    context: Record<string, any>;
+}
+declare function getSapisidFromCookieString(cookieString?: string): string | null;
+declare function getSApiSidHash(sapisid: string, origin?: string): Promise<string | null>;
+declare function getInnerTubeConfig(injectedConfig?: Partial<InnerTubeConfig> | null, customFetch?: typeof globalThis.fetch): Promise<InnerTubeConfig>;
 declare class Client {
     apiKey: string | null;
     clientVersion: string;
     idToken: string | null;
     cookie: string;
+    fetch: typeof globalThis.fetch;
+    cache?: Cache;
     constructor(options?: ClientOptions);
-    /**
-     * Asynchronously resolves config parameters if apiKey is not set yet.
-     * Fetches and parses YouTube's home page HTML using the scraper logic.
-     */
     ensureConfig(): Promise<void>;
     /**
-     * Dispatches an authenticated or unauthenticated POST request to the specified InnerTube endpoint.
+     * Standard InnerTube request using the WEB client (useful for authenticated endpoints).
      */
     request(endpoint: string, payload: any): Promise<any>;
     /**
-     * Searches YouTube for the given query.
+     * Specialized request for the /player endpoint that loops through client profiles
+     * to bypass IP blocks or Captcha walls.
      */
+    requestPlayerWithFallback(videoId: string): Promise<any>;
     search(query: string, options?: {
         type?: 'video' | 'playlist' | 'channel' | 'all';
     }): Promise<SearchResult>;
-    /**
-     * Gets metadata for a specific video.
-     */
-    getVideo(videoId: string): Promise<Video>;
-    /**
-     * Gets metadata and videos for a specific playlist.
-     */
-    getPlaylist(playlistId: string): Promise<Playlist>;
+    findOne(query: string, options?: {
+        type?: 'video' | 'playlist' | 'channel' | 'all';
+    }): Promise<SearchItem | undefined>;
+    getVideo(videoId: string): Promise<Video | LiveVideo>;
+    getPlaylist(playlistId: string): Promise<Playlist | MixPlaylist>;
+    getChannel(channelId: string): Promise<Channel | undefined>;
+    getVideoTranscript(videoId: string, languageCode?: string): Promise<Caption[] | undefined>;
 }
 
 /**
- * comments.ts
- * Scrapes YouTube video comments using InnerTube endpoints and HTML scraping.
+ * scraper.ts
+ * Scrapes user-specific YouTube feeds: History, Likes, Watch Later, and Custom Playlists.
  * Works client-side (Chrome extensions, desktop apps, or CORS-proxied environments).
  */
+interface VideoEntry {
+    title: string;
+    channel: string;
+}
+interface CustomPlaylist {
+    url: string;
+}
 
-interface CommentEntry {
-    author: string;
-    text: string;
-    publishedTime: string;
-    likeCount: number;
-    commentId: string;
+interface CustomPlaylistData {
+    id: string;
+    entries: VideoEntry[];
 }
-interface CommentsApiRequestOptions {
-    headers: Record<string, string>;
-    body: string;
+interface TasteData {
+    historyEntries: VideoEntry[];
+    likesEntries: VideoEntry[];
+    wlEntries: VideoEntry[];
+    dislikesEntries: VideoEntry[];
+    customPlaylistsData: CustomPlaylistData[];
 }
 /**
- * Creates options for the InnerTube /next API call to fetch comments.
- * @param continuationToken - Continuation token for the next page of comments.
- * @param clientVersion - YouTube client version.
- * @returns Options with headers and stringified body.
+ * Fetches the HTML of a YouTube page and extracts `ytInitialData`.
+ * @param url - The URL to fetch.
+ * @returns The parsed ytInitialData object or null.
  */
-declare function createCommentsApiRequestOptions(continuationToken: string, clientVersion?: string): CommentsApiRequestOptions;
+declare function fetchYtInitialData(url: string): Promise<any>;
 /**
- * Fetches comment list for a YouTube video, paginating with continuation tokens.
- * @param videoId - The YouTube Video ID.
- * @param count - Number of comments to retrieve.
- * @param injectedConfig - InnerTube config parameters.
- * @returns Scraped comments.
+ * Recursively scans a JSON object to extract video entries { title, channel }.
+ * Handles both the legacy videoRenderer and the newer lockupViewModel schemas.
+ * @param data - The JSON object to search.
+ * @returns Array of extracted video entries.
  */
-declare function fetchCommentsFromYouTube(videoId: string, count?: number, injectedConfig?: Partial<InnerTubeConfig> | null): Promise<CommentEntry[]>;
+declare function extractVideoEntries(data: any): VideoEntry[];
+/**
+ * Recursively searches for the continuation token in an InnerTube response.
+ * @param obj - InnerTube response subtree.
+ * @returns The token or null.
+ */
+declare function findContinuationToken(obj: any): string | null;
+/**
+ * Fetches video list from a specific InnerTube browse ID, paginating if needed.
+ * @param apiKey - InnerTube API Key.
+ * @param clientVersion - InnerTube client version string.
+ * @param idToken - Identity Token.
+ * @param browseId - Target feed ID (e.g. 'FEhistory', 'VLLL', 'VLWL').
+ * @param limit - Maximum entries to fetch.
+ * @returns Array of videos.
+ */
+declare function fetchInnerTubeFeed(apiKey: string, clientVersion: string, idToken: string | null, browseId: string, limit?: number): Promise<VideoEntry[]>;
+/**
+ * Scrapes History, Liked videos, Watch Later, and any custom playlists.
+ * Tries the InnerTube JSON API first, then falls back to HTML-scraping + paginating if needed.
+ * @param injectedConfig - Preconfigured InnerTube parameters.
+ * @param customPlaylists - Custom playlist definitions with URLs/IDs.
+ * @param limit - Maximum items to retrieve per feed.
+ * @returns Scraped feeds.
+ */
+declare function scrapeTasteData(injectedConfig?: Partial<InnerTubeConfig> | null, customPlaylists?: CustomPlaylist[], limit?: number): Promise<TasteData>;
 
 /**
  * subtitles.ts
  * Scrapes and parses subtitles/transcripts for a YouTube video.
  * Works client-side (Chrome extensions, desktop apps, or CORS-proxied environments) and server-side.
  */
+
 interface TranscriptSegment {
     start: number;
     duration: number;
@@ -294,10 +491,93 @@ declare function extractPlayerResponse(html: string): any;
 declare function parseXmlTranscriptRegex(xmlText: string): TranscriptSegment[];
 /**
  * Fetches and parses the subtitles/captions transcript for a video in the requested language.
+ * Uses InnerTube API with Client profiles fallback, and json3 extraction for better stability.
  * @param videoId - The YouTube Video ID.
  * @param language - The desired language code (e.g. 'en', 'it', 'es').
  * @returns Array of transcript segments.
  */
-declare function fetchSubtitlesFromYouTube(videoId: string, language?: string): Promise<TranscriptSegment[]>;
+declare function fetchSubtitlesFromYouTube(videoId: string, language?: string, clientOrOptions?: Client | ClientOptions): Promise<TranscriptSegment[]>;
+
+/**
+ * Convert transcript segments to SubRip (SRT) format.
+ *
+ * @param segments - Array of transcript segments.
+ * @returns A string in SRT format with sequence numbers and `HH:MM:SS,mmm` timestamps.
+ */
+declare function toSRT(segments: TranscriptSegment[]): string;
+/**
+ * Convert transcript segments to WebVTT (VTT) format.
+ *
+ * @param segments - Array of transcript segments.
+ * @returns A string in VTT format with `WEBVTT` header and `HH:MM:SS.mmm` timestamps.
+ */
+declare function toVTT(segments: TranscriptSegment[]): string;
+/**
+ * Convert transcript segments to plain text.
+ *
+ * @param segments - Array of transcript segments.
+ * @param separator - String to join segments with. Defaults to `'\n'`.
+ * @returns A plain text string with segments joined by the separator.
+ */
+declare function toPlainText(segments: TranscriptSegment[], separator?: string): string;
+
+/**
+ * comments.ts
+ * Scrapes YouTube video comments using InnerTube endpoints and HTML scraping.
+ * Works client-side (Chrome extensions, desktop apps, or CORS-proxied environments).
+ */
+
+interface CommentEntry {
+    author: string;
+    text: string;
+    publishedTime: string;
+    likeCount: number;
+    commentId: string;
+}
+interface CommentsApiRequestOptions {
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Creates options for the InnerTube /next API call to fetch comments.
+ * @param continuationToken - Continuation token for the next page of comments.
+ * @param clientVersion - YouTube client version.
+ * @returns Options with headers and stringified body.
+ */
+declare function createCommentsApiRequestOptions(continuationToken: string, clientVersion?: string): CommentsApiRequestOptions;
+/**
+ * Fetches comment list for a YouTube video, paginating with continuation tokens.
+ * @param videoId - The YouTube Video ID.
+ * @param count - Number of comments to retrieve.
+ * @param injectedConfig - InnerTube config parameters.
+ * @returns Scraped comments.
+ */
+declare function fetchCommentsFromYouTube(videoId: string, count?: number, injectedConfig?: Partial<InnerTubeConfig> | null): Promise<CommentEntry[]>;
+
+declare class Chat extends Base {
+    id: string;
+    message: string;
+    author: BaseChannel;
+    timestamp: number;
+    constructor(client: Client, data?: any);
+    load(data: any): Chat;
+}
+
+/**
+ * Convenience helper to search YouTube without initializing a Client manually.
+ * @param query The search query string.
+ * @param options ClientOptions & Search filtering options.
+ * @returns SearchResult object with video/playlist/channel items.
+ */
+declare function searchYouTube(query: string, options?: {
+    type?: 'video' | 'playlist' | 'channel' | 'all';
+} & ClientOptions): Promise<SearchResult>;
+/**
+ * Convenience helper to get a video's metadata and playback/streaming data.
+ * @param videoId The video ID.
+ * @param options ClientOptions (e.g. for proxy/fetch customization).
+ * @returns Video object with streamingData populated.
+ */
+declare function getVideoPlayback(videoId: string, options?: ClientOptions): Promise<Video | LiveVideo>;
 
-export { Base, BaseVideo, ChannelCompact, type ChannelInfo, Client, type ClientOptions, type CommentEntry, type CommentsApiRequestOptions, Continuable, type CustomPlaylist, type CustomPlaylistData, type InnerTubeConfig, Playlist, PlaylistCompact, PlaylistVideos, type SearchItem, SearchResult, type TasteData, type Thumbnail, Thumbnails, type TranscriptSegment, Video, VideoCompact, type VideoEntry, createCommentsApiRequestOptions, extractPlayerResponse, extractVideoEntries, fetchCommentsFromYouTube, fetchInnerTubeFeed, fetchSubtitlesFromYouTube, fetchYtInitialData, findContinuationToken, getInnerTubeConfig, getSApiSidHash, getSapisidFromCookie, parseXmlTranscriptRegex, scrapeTasteData };
+export { Base, BaseChannel, BaseVideo, type Cache, Caption, CaptionLanguage, Channel, ChannelCompact, type ChannelInfo, ChannelLive, ChannelPlaylists, ChannelPosts, ChannelShorts, ChannelVideos, Chat, Client, type ClientOptions, type ClientProfile, Comment, type CommentEntry, CommentReplies, type CommentsApiRequestOptions, Continuable, type CustomPlaylist, type CustomPlaylistData, type Format, type InnerTubeConfig, LiveVideo, MixPlaylist, Playlist, PlaylistCompact, PlaylistVideos, type SearchItem, SearchResult, type StreamingData, type TasteData, type Thumbnail, Thumbnails, type TranscriptSegment, Video, VideoCaptions, VideoComments, VideoCompact, type VideoEntry, VideoRelated, createCommentsApiRequestOptions, extractPlayerResponse, extractVideoEntries, fetchCommentsFromYouTube, fetchInnerTubeFeed, fetchSubtitlesFromYouTube, fetchYtInitialData, findContinuationToken, getInnerTubeConfig, getSApiSidHash, getSapisidFromCookieString, getVideoPlayback, parseXmlTranscriptRegex, scrapeTasteData, searchYouTube, toPlainText, toSRT, toVTT };