@vizlook/sdk/dist/index.d.ts

Vizlook JavaScript SDK

/**
 * Video category
 */
type Category = "Healthcare" | "Ecommerce" | "Tech" | "Finance" | "Education";
/**
 * Configure what search results include.
 * @typedef {Object} ContentOptions
 * @property {boolean} [includeTranscription] - Whether to include video transcription in the search results.
 * @property {boolean} [includeSummary] - Whether to include video summary in the search results.
 */
interface ContentOptions {
    includeTranscription?: boolean;
    includeSummary?: boolean;
}
/**
 * Basic search options for performing a search query.
 * @typedef {Object} BaseSearchOptions
 * @property {Category} [category] - A video category.
 * @property {string | number} [startPublishedDate] - Start date for results based on video published date in millisecond or ISO timestamp string.
 * @property {string | number} [endPublishedDate] - End date for results based on video published date in millisecond or ISO timestamp string.
 * @property {number} [maxResults] - The maximum number of search results to return. The default value is 10 and the maximum value is 20.
 */
interface BaseSearchOptions {
    category?: Category;
    startPublishedDate?: string | number;
    endPublishedDate?: string | number;
    maxResults?: number;
}
type SearchOptions = BaseSearchOptions & ContentOptions;
/**
 * Video clip
 * @typedef {Object} VideoClip
 * @property {number} [startTime] - Start time of the video clip in seconds.
 * @property {number} [endTime] - End time of the video clip in seconds.
 * @property {string} [visualDescription] - Visual description of the video clip.
 */
interface VideoClip {
    startTime: number;
    endTime: number;
    visualDescription: string;
}
/**
 * Audio clip
 * @typedef {Object} AudioClip
 * @property {number} [startTime] - Start time of the audio clip in seconds.
 * @property {number} [endTime] - End time of the audio clip in seconds.
 * @property {string} [transcription] - Transcription of the audio clip.
 * @property {string} [speakerId] - The speaker ID of the audio clip, such as 'speaker_1'. If the speaker is identified, it will be set to the speaker's name.
 */
interface AudioClip {
    startTime: number;
    endTime: number;
    transcription: string;
    speakerId: string;
}
/**
 * Video transcription
 * @typedef {Object} VideoTranscription
 * @property {VideoClip[]} [videoClips] - Video clips with visual descriptions.
 * @property {AudioClip[]} [audioClips] - Audio clips with transcriptions.
 */
interface VideoTranscription {
    videoClips: VideoClip[];
    audioClips: AudioClip[];
}
/**
 * The video clip that best matches the query.
 * @typedef {Object} VideoHighlight
 * @property {number} [startTime] - Start time of the video clip in seconds.
 * @property {number} [endTime] - End time of the video clip in seconds.
 * @property {string} [visualDescription] - Visual description of the video clip.
 * @property {string} [audioTranscription] - Audio transcription of the video clip.
 */
interface VideoHighlight {
    startTime: number;
    endTime: number;
    visualDescription: string;
    audioTranscription?: string;
}
/**
 * Video summary
 * @typedef {Object} VideoSummary
 * @property {string} [overallSummary] - Overall summary of the video.
 * @property {Object[]} [sectionSummaries] - Section summaries of the video.
 * @property {number} [sectionSummaries.startTime] - Start time of the section in seconds.
 * @property {number} [sectionSummaries.endTime] - End time of the section in seconds.
 * @property {string} [sectionSummaries.title] - Title of the section.
 * @property {string} [sectionSummaries.summary] - Summary of the section.
 */
interface VideoSummary {
    overallSummary: string;
    sectionSummaries: {
        startTime: number;
        endTime: number;
        title: string;
        summary: string;
    }[];
}
/**
 * @typedef {Object} SearchResultItem
 */
interface SearchResultItem {
    url: string;
    title: string;
    description: string;
    thumbnail: {
        url: string;
        width: number;
        height: number;
    };
    author: {
        name: string;
        url?: string;
        avatar: string;
    };
    publishedDate: string;
    duration: number;
    favicon: string;
    score?: number;
    highlights: VideoHighlight[];
    transcription?: VideoTranscription;
    summary?: VideoSummary;
}
/**
 * Search response
 * @typedef {Object} SearchResponse
 * @property {SearchResultItem[]} results - Search results.
 * @property {Object} dollarCost - Dollar cost of the search.
 * @property {number} dollarCost.total - Total dollar cost.
 * @property {Object} dollarCost.breakdown - Dollar cost breakdown.
 * @property {number} dollarCost.breakdown.search - Search dollar cost.
 * @property {number} dollarCost.breakdown.summary - Summary dollar cost.
 * @property {number} dollarCost.breakdown.transcription - Transcription dollar cost.
 */
interface SearchResponse {
    results: SearchResultItem[];
    dollarCost: {
        total: number;
        breakdown?: {
            search: number;
            summary?: number;
            transcription?: number;
        };
    };
}
/**
 * @typedef {Object} AnswerOptions
 * @property {boolean} [includeTranscription] - Whether to include video transcription in the answer citations.
 */
interface AnswerOptions {
    includeTranscription?: boolean;
}
/**
 * @typedef {Object} AnswerCitationItem
 */
interface AnswerCitationItem {
    url: string;
    title: string;
    description: string;
    thumbnail: {
        url: string;
        width: number;
        height: number;
    };
    author: {
        name: string;
        url?: string;
        avatar: string;
    };
    publishedDate: string;
    duration: number;
    favicon: string;
    score?: number;
    highlights: VideoHighlight[];
    transcription?: VideoTranscription;
}
/**
 * @typedef {Object} AnswerResponse
 * @property {string} answer - Answer to the query.
 * @property {AnswerCitationItem[]} citations - Answer citations.
 * @property {Object} dollarCost - Dollar cost of the answer.
 * @property {number} dollarCost.total - Total dollar cost.
 */
interface AnswerResponse {
    answer: string;
    citations: AnswerCitationItem[];
    dollarCost: {
        total: number;
    };
}
/**
 * @typedef {Object} AnswerStreamChunk
 * @property {string} type - Type of the stream chunk.
 * @property {string} data - Data of the stream chunk.
 */
type AnswerStreamChunk = {
    type: "answer-chunk";
    data: string;
} | {
    type: "data-citations";
    data: {
        citations: AnswerCitationItem[];
    };
} | {
    type: "data-cost";
    data: {
        dollarCost: {
            total: number;
        };
    };
} | {
    type: "error";
    data: {
        errorText: string;
    };
};
/**
 * @typedef {Object} BaseVideoContentsOptions
 * @property {string} [crawlMode] - Crawl mode, default is 'Never'
 */
interface BaseVideoContentsOptions {
    crawlMode?: "Never" | "Fallback" | "Always";
}
type VideoContentsOptions = BaseVideoContentsOptions & ContentOptions;
/**
 * @typedef {string} VideoContentErrorType - Error type when getting video contents
 */
type VideoContentErrorType = "FAILED_TO_PARSE_URL" | "CACHE_NOT_FOUND" | "CRAWL_SOURCE_FAIL" | "CRAWL_NOT_FOUND" | "CRAWL_VIDEO_DURATION_EXCEEDS_LIMIT" | "CRAWL_SERVER_ERROR" | "CRAWL_TIMEOUT";
/**
 * @typedef {Object} VideoContent
 * @property {Object} data - Video content data.
 * @property {string} data.url - Video page url.
 * @property {string} data.title - Video title.
 * @property {string} data.description - Video description.
 * @property {Object} data.thumbnail - Video thumbnail.
 * @property {string} data.thumbnail.url - Thumbnail URL.
 * @property {number} data.thumbnail.width - Thumbnail width.
 * @property {number} data.thumbnail.height - Thumbnail height.
 * @property {Object} data.author - Video author.
 * @property {string} data.author.name - Author name.
 * @property {string} data.author.url - Author page url.
 * @property {string} data.author.avatar - Author avatar.
 * @property {string} data.publishedDate - Video published date, ISO timestamp string.
 * @property {number} data.duration - Video duration in seconds.
 * @property {string} data.favicon - Video page favicon.
 * @property {VideoTranscription} data.transcription - Video transcription.
 * @property {VideoSummary} data.summary - Video summary.
 * @property {Object} status - Video content status.
 * @property {string} status.url - Video page url.
 * @property {string} status.status - Video content status.
 * @property {Object} status.error - Video content error if has error.
 * @property {VideoContentErrorType} status.error.type - Error type.
 * @property {string} status.error.message - Error message if has message.
 * @property {boolean} status.isLiveCrawl - Whether the video content is crawled live.
 */
interface VideoContent {
    data?: {
        url: string;
        title: string;
        description: string;
        thumbnail: {
            url: string;
            width: number;
            height: number;
        };
        author: {
            name: string;
            url?: string;
            avatar: string;
        };
        publishedDate: string;
        duration: number;
        favicon: string;
        transcription?: VideoTranscription;
        summary?: VideoSummary;
    };
    status: {
        url: string;
        status: "Success" | "Fail";
        error?: {
            type: VideoContentErrorType;
            message?: string;
        };
        isLiveCrawl?: boolean;
    };
}
/**
 * @typedef {Object} VideoContentsResponse
 * @property {VideoContent[]} results - Video contents.
 * @property {Object} dollarCost - Dollar cost of the video contents.
 * @property {number} dollarCost.total - Total dollar cost.
 * @property {Object} dollarCost.breakdown - Dollar cost breakdown.
 * @property {number} dollarCost.breakdown.transcription - Transcription dollar cost.
 * @property {number} dollarCost.breakdown.summary - Summary dollar cost.
 * @property {number} dollarCost.breakdown.crawl - Live crawl dollar cost.
 */
interface VideoContentsResponse {
    results: VideoContent[];
    dollarCost: {
        total: number;
        breakdown?: {
            transcription?: number;
            summary?: number;
            crawl?: number;
        };
    };
}

interface VizlookOptions {
    apiKey?: string;
    baseURL?: string;
}
/**
 * The Vizlook class encapsulates the API's endpoints.
 */
declare class Vizlook {
    private baseURL;
    private headers;
    /**
     * Constructs the Vizlook SDK client.
     * @param {VizlookOptions} [VizlookOptions] - The options for the Vizlook SDK client.
     * @param {string} [VizlookOptions.apiKey] - The API key for authentication.
     * @param {string} [VizlookOptions.baseURL] - The base URL of the Vizlook API.
     */
    constructor({ apiKey, baseURL }?: VizlookOptions);
    /**
     * Makes a request to the Vizlook API.
     * @param {string} endpoint - The API endpoint to call.
     * @param {string} method - The HTTP method to use.
     * @param {any} [body] - The request body for POST requests.
     * @param {Record<string, any>} [params] - The query parameters.
     * @returns {Promise<T>} The response from the API.
     * @throws {VizlookError} When any API request fails with structured error information.
     */
    request<T = unknown>(endpoint: string, method: string, body?: any, params?: Record<string, any>, headers?: Record<string, string>): Promise<T>;
    /**
     * Performs a search with a query.
     *
     * @param {string} query - The query string. The query is limited to 500 characters.
     * @param {SearchOptions} [options] - Additional search options
     * @returns {Promise<SearchResponse>} A list of relevant search results.
     */
    search(query: string, options?: SearchOptions): Promise<SearchResponse>;
    /**
     * Answers a query in non-stream mode.
     *
     * @param {string} query - The query string. The query is limited to 500 characters.
     * @param {AnswerOptions} [options] - Additional answer options
     * @returns {Promise<AnswerResponse>} The answer to the query.
     */
    answer(query: string, options?: AnswerOptions): Promise<AnswerResponse>;
    /**
     * Answers a query in stream mode.
     *
     * @param {string} query - The query string. The query is limited to 500 characters.
     * @param {AnswerOptions} [options] - Additional answer options
     * @returns {Promise<AnswerStreamChunk>} The stream of answer chunks.
     *
     * Example:
     * ```ts
     * for await (const chunk of vizlook.streamAnswer("How to learn python?", {
     *   needTranscription: true,
     * })) {
     *   console.log(chunk);
     * }
     * ```
     */
    streamAnswer(query: string, options?: AnswerOptions): AsyncGenerator<AnswerStreamChunk>;
    /**
     * Retrieves contents of videos based on URLs.
     *
     * @param {string | string[]} urls - A URL or array of URLs. Only support YouTube URLs for now, such as https://www.youtube.com/watch?v=xxxxxx
     * @param {VideoContentsOptions} [options] - Additional options for retrieving video contents.
     * @returns {Promise<VideoContentsResponse>} A list of video contents for the requested URLs.
     */
    getVideoContents(urls: string | string[], options?: VideoContentsOptions): Promise<VideoContentsResponse>;
}

declare enum HttpStatusCode {
    BadRequest = 400,
    Unauthorized = 401,
    InsufficientBalance = 402,
    TooManyRequests = 429,
    InternalServerError = 500
}
/**
 * Error class for Vizlook API errors
 */
declare class VizlookError extends Error {
    statusCode: number;
    timestamp: string;
    path?: string;
    extra?: Record<string, any>;
    /**
     * @param {string} [message] - Error message
     * @param {number} [statusCode] - HTTP status code
     * @param {Object} [options] - Error options
     * @param {string} [options.timestamp] - ISO timestamp string
     * @param {string} [options.path] - Path that caused the error
     * @param {Record<string, any>} [options.extra] - Extra information
     */
    constructor(message: string, statusCode: number, options?: {
        timestamp?: string;
        path?: string;
        extra?: Record<string, any>;
    });
}

export { type AnswerCitationItem, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AudioClip, type BaseSearchOptions, type BaseVideoContentsOptions, type Category, type ContentOptions, HttpStatusCode, type SearchOptions, type SearchResponse, type SearchResultItem, type VideoClip, type VideoContent, type VideoContentErrorType, type VideoContentsOptions, type VideoContentsResponse, type VideoHighlight, type VideoSummary, type VideoTranscription, Vizlook, VizlookError, type VizlookOptions, Vizlook as default };