opex-yt-info/index.d.ts

Node.js library for searching YouTube (videos, channels, live), getting video/playlist metadata, and fetching homepage/trending videos.

// index.d.ts
export { getYouTubeVideoId, getYouTubePlaylistId } from 'opex-yt-id';

// --- Options Interfaces ---

export interface SearchOptions {
  /** Search result page number to start scraping from. Default: 1 */
  pageStart?: number;
  /** Search result page number to end scraping at. Default: 1 */
  pageEnd?: number;
  /** Language code (e.g., 'en', 'es', 'ru'). Affects search results language. */
  hl?: string;
  /** Geographic location code (e.g., 'US', 'GB', 'RU'). Affects search result relevance. */
  gl?: string;
  /** YouTube category filter (e.g., 'music'). Limited support in yt-search. */
  category?: string;
  /** YouTube SP parameter (for advanced filtering, usually obtained from YT URLs). */
  sp?: string;
  /** Custom User-Agent string for HTTP requests. */
  userAgent?: string;
}

// Options for single item lookups (getVideo, getPlaylist)
export interface GetOptions {
  /** Language code (e.g., 'en', 'es', 'ru'). */
  hl?: string;
  /** Geographic location code (e.g., 'US', 'GB', 'RU'). */
  gl?: string;
  /** Custom User-Agent string for HTTP requests. */
  userAgent?: string;
}


// --- Result Structures (Based on yt-search) ---

export interface Author {
  name: string;
  url: string;
}

export interface Duration {
  seconds: number;
  timestamp: string; // e.g., "3:10" or "1:05:30"
  toString: () => string;
}

// Base Video structure from search results
export interface Video {
  type: 'video';
  videoId: string;
  url: string;
  title: string;
  description: string; // May be truncated
  image: string;       // Thumbnail URL
  thumbnail: string;   // Thumbnail URL (alias for image)
  seconds: number;     // Duration in seconds
  timestamp: string;   // Duration formatted (e.g., "3:10")
  duration: Duration;
  ago: string;         // Upload time relative (e.g., "1 year ago")
  views: number;
  author: Author;
}

// Detailed Video structure (adds fields potentially available from yt-search videoId lookup)
export interface VideoDetail extends Video {
  genre?: string;      // Genre if provided by yt-search
  uploadDate?: string; // Upload date (YYYY-MM-DD) if provided by yt-search
}

export interface Channel {
  type: 'channel';
  name: string;
  url: string;
  baseUrl?: string;    // Relative URL path (e.g., '/@MrBeast')
  id?: string;         // Channel ID (if available from search)
  title: string;       // Usually the same as name
  about?: string;      // Short description/snippet from search
  image: string;       // Avatar URL
  thumbnail: string;   // Avatar URL (alias for image)
  videoCount: number;
  videoCountLabel: string; // e.g., "1.2K videos"
  verified: boolean;
  subCount: number;    // Approximate subscriber count (parsed number)
  subCountLabel: string; // e.g., "1.2M subscribers" (original label)
}

export interface LiveVideo {
  type: 'live';
  videoId: string;
  url: string;
  title: string;
  description: string;
  image: string;
  thumbnail: string;
  watching: number;    // Current viewers
  author: Author;
  status: 'LIVE' | 'UPCOMING';
  startTime?: number;  // Unix timestamp (ms) for upcoming streams
  startDate?: string;  // Formatted date string for upcoming streams (from yt-search)
}

// Summary structure for playlists found via general search
export interface PlaylistSummary {
    type: 'list';
    listId: string;
    url: string;
    title: string;
    thumbnail: string;
    image: string; // Alias
    videoCount: number;
    author: Author;
}

// Represents a summary of a video within a playlist (from getPlaylist)
export interface PlaylistVideoSummary {
  title: string;
  videoId: string;
  listId: string;      // ID of the parent playlist
  thumbnail: string;
  duration: Duration;  // Duration parsed from yt-search format (e.g., PT4M13S)
  author: Author;      // Usually the playlist author, as yt-search might not provide per-video author here
}

// Represents detailed playlist info fetched by getPlaylist using yt-search
export interface PlaylistDetail {
  title: string;
  listId: string;
  url: string;
  size?: number;       // Video count
  views?: number;      // Playlist views (if provided by yt-search)
  date?: string;       // Last updated date (YYYY-MM-DD) if provided by yt-search
  image?: string;      // Playlist thumbnail URL
  thumbnail?: string;  // Playlist thumbnail URL (alias for image)
  videos: PlaylistVideoSummary[]; // Array of video summaries within the playlist
  author: Author;      // Playlist creator
}


// --- Exported Function Signatures ---

/**
 * Searches for YouTube videos using yt-search.
 * @param query Search query.
 * @param options Search options.
 * @returns Array of video results.
 */
export function searchVideos(query: string, options?: SearchOptions): Promise<Video[]>;

/**
 * Searches for YouTube channels using yt-search.
 * @param query Search query.
 * @param options Search options.
 * @returns Array of channel results.
 */
export function searchChannels(query: string, options?: SearchOptions): Promise<Channel[]>;

/**
 * Searches for YouTube live streams using yt-search.
 * @param query Search query.
 * @param options Search options.
 * @returns Array of live stream results.
 */
export function searchLive(query: string, options?: SearchOptions): Promise<LiveVideo[]>;

/**
 * Searches for YouTube videos, channels, live streams, and potentially playlists using yt-search.
 * Note: Playlist results from yt-search might be included but are often limited/inconsistent.
 * @param query Search query.
 * @param options Search options.
 * @returns Combined array of results.
 */
export function searchAll(query: string, options?: SearchOptions): Promise<Array<Video | Channel | LiveVideo | PlaylistSummary>>;

/**
 * Gets basic metadata for a specific YouTube video using yt-search.
 * Accepts either a Video ID or a YouTube Video URL.
 * Note: The detail level depends on what yt-search provides for single video lookups.
 * @param videoIdOrUrl The ID or URL of the video.
 * @param options Options (hl, gl, userAgent).
 * @returns Basic video details or null if not found/error.
 */
export function getVideo(videoIdOrUrl: string, options?: GetOptions): Promise<VideoDetail | null>;

/**
 * Gets basic metadata and a list of videos for a specific YouTube playlist using yt-search.
 * Accepts either a Playlist ID or a YouTube Playlist URL.
 * Note: The detail level and number of videos returned depend on yt-search's capabilities.
 * @param playlistIdOrUrl The ID or URL of the playlist.
 * @param options Options (hl, gl, userAgent).
 * @returns Basic playlist details or null if not found/error.
 */
export function getPlaylist(playlistIdOrUrl: string, options?: GetOptions): Promise<PlaylistDetail | null>;

// Functions not supported by this yt-search-only implementation:
// getHomepage
// getTrending
// getSuggestions