@supadata/js/dist/index.d.ts

TypeScript / JavaScript SDK for Supadata API

interface TranscriptChunk {
    text: string;
    offset: number;
    duration: number;
    lang: string;
}
interface Transcript {
    content: TranscriptChunk[] | string;
    lang: string;
    availableLangs: string[];
}
interface TranslatedTranscript {
    content: TranscriptChunk[] | string;
    lang: string;
}
interface Scrape {
    url: string;
    content: string;
    name: string;
    description: string;
    ogUrl: string;
    countCharacters: number;
    urls: string[];
}
interface SiteMap {
    urls: string[];
}
interface CrawlRequest {
    url: string;
    limit?: number;
}
interface Crawl {
    jobId: string;
}
interface CrawlJob {
    status: 'scraping' | 'completed' | 'failed' | 'cancelled';
    pages?: Scrape[];
    next?: string;
}
interface SupadataConfig {
    apiKey: string;
    baseUrl?: string;
}
declare class SupadataError extends Error {
    error: 'invalid-request' | 'internal-error' | 'transcript-unavailable' | 'not-found' | 'unauthorized' | 'upgrade-required' | 'limit-exceeded';
    details: string;
    documentationUrl: string;
    constructor(error: {
        error: SupadataError['error'];
        message?: string;
        details?: string;
        documentationUrl?: string;
    });
}
interface YoutubeVideo {
    id: string;
    title: string;
    description: string;
    duration: number;
    channel: {
        id: string;
        name: string;
    };
    tags: string[];
    thumbnail: string;
    uploadDate: string;
    viewCount: number;
    likeCount: number;
    transcriptLanguages: string[];
}
interface YoutubeChannel {
    id: string;
    name: string;
    handle: string;
    description: string;
    subscriberCount: number;
    videoCount: number;
    thumbnail: string;
    banner: string;
}
interface YoutubePlaylist {
    id: string;
    title: string;
    videoCount: number;
    viewCount: number;
    lastUpdated: string;
    description: string;
    thumbnail: string;
}
interface YoutubeBatchSource {
    videoIds?: string[];
    playlistId?: string;
    channelId?: string;
    limit?: number;
}
interface YoutubeTranscriptBatchRequest extends YoutubeBatchSource {
    lang?: string;
    text?: boolean;
}
interface YoutubeVideoBatchRequest extends YoutubeBatchSource {
}
interface YoutubeBatchJob {
    jobId: string;
}
type YoutubeBatchJobStatus = 'queued' | 'active' | 'completed' | 'failed';
interface YoutubeBatchResultItem {
    videoId: string;
    transcript?: Transcript;
    video?: YoutubeVideo;
    errorCode?: string;
}
interface YoutubeBatchStats {
    total: number;
    succeeded: number;
    failed: number;
}
interface YoutubeBatchResults {
    status: YoutubeBatchJobStatus;
    results?: YoutubeBatchResultItem[];
    stats?: YoutubeBatchStats;
    completedAt?: string;
}

declare class BaseClient {
    protected config: SupadataConfig;
    constructor(config: SupadataConfig);
    protected fetch<T>(endpoint: string, params?: Record<string, any>, method?: 'GET' | 'POST'): Promise<T>;
    protected fetchUrl<T>(url: string, method?: 'GET' | 'POST', body?: Record<string, any>): Promise<T>;
}

/**
 * Ensures exactly one property from the specified keys is provided.
 * @example
 * // Valid: { url: "..." } or { videoId: "..." }
 * // Invalid: {} or { url: "...", videoId: "..." }
 */
type ExactlyOne<T, Keys extends keyof T> = {
    [K in Keys]: {
        [P in K]-?: T[P];
    } & {
        [P in Exclude<Keys, K>]?: never;
    };
}[Keys] & Omit<T, Keys>;
type TranscriptParams = {
    lang?: string;
    text?: boolean;
} & ExactlyOne<{
    videoId: string;
    url: string;
}, 'videoId' | 'url'>;
interface TranslateParams extends Omit<TranscriptParams, 'lang'> {
    lang: string;
}
interface ResourceParams {
    id: string;
}
interface ChannelVideosParams extends ResourceParams {
    limit?: number;
    type?: 'video' | 'short' | 'live' | 'all';
}
interface PlaylistVideosParams extends ResourceParams {
    limit?: number;
}
interface VideoIds {
    videoIds: string[];
    shortIds: string[];
    liveIds: string[];
}
declare class YouTubeService extends BaseClient {
    /**
     * Handles YouTube Transcript operations.
     */
    transcript: ((params: TranscriptParams) => Promise<Transcript>) & {
        /**
         * Batch fetches transcripts for multiple YouTube videos.
         * @param params - Parameters for the transcript batch job
         * @param params.videoIds - Array of YouTube video IDs to fetch transcripts for
         * @param params.lang - The language code for the transcripts (optional)
         * @param params.limit - Maximum number of videos to process (optional, default: 10, max: 5000)
         * @param params.text - Whether to return only the text content (optional)
         * @returns A promise that resolves to a YoutubeBatchJob object with the job ID
         */
        batch: (params: YoutubeTranscriptBatchRequest) => Promise<YoutubeBatchJob>;
    };
    /**
     * Handles YouTube video operations.
     */
    video: ((params: ResourceParams) => Promise<YoutubeVideo>) & {
        /**
         * Batch fetches metadata for multiple YouTube videos.
         * @param params - Parameters for the video metadata batch job
         * @param params.videoIds - Array of YouTube video IDs to fetch metadata for
         * @param params.limit - Maximum number of videos to process (optional, default: 10, max: 5000)
         * @returns A promise that resolves to a YoutubeBatchJob object with the job ID
         */
        batch: (params: YoutubeVideoBatchRequest) => Promise<YoutubeBatchJob>;
    };
    /**
     * Handles YouTube channel operations.
     */
    channel: ((params: ResourceParams) => Promise<YoutubeChannel>) & {
        /**
         * Fetches the videos of a YouTube channel.
         * @param params - The parameters required to fetch the YouTube channel videos
         * @param params.id - The YouTube channel ID
         * @param params.limit - The maximum number of videos to fetch (default: 30, max: 5000)
         * @param params.type - The type of videos to fetch ('video', 'short', 'live', or 'all', default: 'video')
         * @returns A promise that resolves to an object containing arrays of video IDs, short IDs, and live IDs
         * @throws {SupadataError} If the limit is invalid (less than 1 or greater than 5000)
         */
        videos: (params: ChannelVideosParams) => Promise<VideoIds>;
    };
    /**
     * Handles YouTube playlist operations.
     */
    playlist: ((params: ResourceParams) => Promise<YoutubePlaylist>) & {
        /**
         * Fetches the videos of a YouTube playlist.
         * @param params - The parameters required to fetch the playlist videos
         * @param params.id - The YouTube playlist ID
         * @param params.limit - The maximum number of videos to fetch (default: 30, max: 5000)
         * @returns A promise that resolves to an object containing arrays of video IDs, short IDs, and live IDs
         * @throws {SupadataError} If the limit is invalid (less than 1 or greater than 5000)
         */
        videos: (params: PlaylistVideosParams) => Promise<VideoIds>;
    };
    /**
     * Handles YouTube batch operations.
     */
    batch: {
        /**
         * Retrieves the status and results of a batch job.
         * @param jobId - The ID of the batch job
         * @returns A promise that resolves to the YoutubeBatchResults containing job status and results
         * @throws {SupadataError} If jobId is not provided
         */
        getBatchResults: (jobId: string) => Promise<YoutubeBatchResults>;
    };
    /**
     * Translates a YouTube video transcript to a specified language.
     * @param params - Parameters for translating the transcript
     * @param params.videoId - The YouTube video ID (mutually exclusive with url)
     * @param params.url - The YouTube video URL (mutually exclusive with videoId)
     * @param params.lang - The target language code for translation
     * @param params.text - Whether to return only the text content (optional)
     * @returns A promise that resolves to a TranslatedTranscript object
     */
    translate: (params: TranslateParams) => Promise<TranslatedTranscript>;
    private validateLimit;
    private validateBatchLimit;
}

declare class WebService extends BaseClient {
    /**
     * Extract content from any web page to Markdown format.
     *
     * @param url - URL of the webpage to scrape
     * @returns A promise that resolves to the scraped content
     */
    scrape(url: string): Promise<Scrape>;
    /**
     * Extract all links found on a webpage.
     *
     * @param url - URL of the webpage to map
     * @returns A promise that resolves to a map of URLs found on the page
     */
    map(url: string): Promise<SiteMap>;
    /**
     * Create a crawl job to extract content from all pages on a website.
     *
     * @param request - Crawl request parameters
     * @param request.url - URL of the website to crawl
     * @param request.limit - Maximum number of pages to crawl (default: 100, max: 5000)
     * @returns A promise that resolves to the crawl job id
     */
    crawl(request: CrawlRequest): Promise<Crawl>;
    /**
     * Get the status and results of a crawl job.
     * Automatically handles pagination to retrieve all pages from the crawl.
     *
     * @param jobId - The ID of the crawl job to retrieve
     * @returns A promise that resolves to the complete crawl job results
     */
    getCrawlResults(jobId: string): Promise<CrawlJob>;
}

declare class Supadata {
    readonly youtube: YouTubeService;
    readonly web: WebService;
    constructor(config: SupadataConfig);
}

export { BaseClient, type ChannelVideosParams, type Crawl, type CrawlJob, type CrawlRequest, type PlaylistVideosParams, type ResourceParams, type Scrape, type SiteMap, Supadata, type SupadataConfig, SupadataError, type Transcript, type TranscriptChunk, type TranscriptParams, type TranslateParams, type TranslatedTranscript, type VideoIds, WebService, YouTubeService, type YoutubeBatchJob, type YoutubeBatchJobStatus, type YoutubeBatchResultItem, type YoutubeBatchResults, type YoutubeBatchSource, type YoutubeBatchStats, type YoutubeChannel, type YoutubePlaylist, type YoutubeTranscriptBatchRequest, type YoutubeVideo, type YoutubeVideoBatchRequest };