brave-search/dist/braveSearch.d.ts

A fully typed Brave Search API wrapper, providing easy access to web search, local POI search, and automatic polling for web search summary feature.

import { BraveSearchOptions, ImageSearchApiResponse, ImageSearchOptions, LocalDescriptionsSearchApiResponse, LocalPoiSearchApiResponse, NewsSearchApiResponse, NewsSearchOptions, PollingOptions, SummarizerOptions, SummarizerSearchApiResponse, WebSearchApiResponse } from "./types";
/**
 * An error class specific to BraveSearch API interactions.
 * It includes additional information about the response data that caused the error.
 */
declare class BraveSearchError extends Error {
    responseData: any;
    /**
     * Initializes a new instance of the BraveSearchError class.
     * @param message The error message.
     * @param responseData The response data that caused the error.
     */
    constructor(message: string, responseData?: any);
}
/**
 * The main class for interacting with the Brave Search API, holding API key for all the requests made with it.
 * It provides methods for web search, image search, local POI search, and summarization.
 */
declare class BraveSearch {
    private apiKey;
    private baseUrl;
    private pollInterval;
    private maxPollAttempts;
    /**
     * Initializes a new instance of the BraveSearch class.
     * @param apiKey The API key for accessing the Brave Search API.
     * @param options
     */
    constructor(apiKey: string, options?: PollingOptions);
    /**
     * Performs a web search using the provided query and options.
     * @param query The search query string.
     * @param options Optional settings to configure the search behavior.
     * @returns A promise that resolves to the search results.
     */
    webSearch(query: string, options?: BraveSearchOptions, signal?: AbortSignal): Promise<WebSearchApiResponse>;
    /**
     * Performs an image search using the provided query and options.
     * @param query The search query string.
     * @param options Optional settings to configure the search behavior.
     * @returns A promise that resolves to the image search results.
     */
    imageSearch(query: string, options?: ImageSearchOptions, signal?: AbortSignal): Promise<ImageSearchApiResponse>;
    newsSearch(query: string, options?: NewsSearchOptions, signal?: AbortSignal): Promise<NewsSearchApiResponse>;
    /**
     * Executes a web search for the provided query and polls for a summary
     * if the query is eligible for a summary and summarizer key is provided in the web search response.
     * The summary is usually ready within 2 seconds after the original web search response is received.
     * @param query The search query string.
     * @param options Optional settings to configure the search behavior.
     * @param summarizerOptions Optional settings specific to summarization.
     * @returns An object containing promises for the web search results and the summarized answer.
     */
    getSummarizedAnswer(query: string, options?: Omit<BraveSearchOptions, "summary">, summarizerOptions?: SummarizerOptions, signal?: AbortSignal): {
        summary: Promise<SummarizerSearchApiResponse | undefined>;
        webSearch: Promise<WebSearchApiResponse>;
    };
    /**
     * Searches for local points of interest using the provided IDs and options.
     * @param ids The IDs of the local points of interest.
     * @returns A promise that resolves to the search results.
     */
    localPoiSearch(ids: string[], signal?: AbortSignal): Promise<LocalPoiSearchApiResponse>;
    /**
     * Retrieves descriptions for local points of interest using the provided IDs and options.
     * @param ids The IDs of the local points of interest.
     * @returns A promise that resolves to the search results.
     */
    localDescriptionsSearch(ids: string[], signal?: AbortSignal): Promise<LocalDescriptionsSearchApiResponse>;
    /**
     * Polls for a summary response after a web search request. This method is suggested by the Brave Search API documentation
     * as the way to retrieve a summary after initiating a web search.
     *
     * @param key The key identifying the summary request.
     * @param options Optional settings specific to summarization.
     * @param signal Optional AbortSignal to cancel the request.
     * @returns A promise that resolves to the summary response if available, or undefined if the summary is not ready.
     * @throws {BraveSearchError} If the summary generation fails or if the summary is not available after maximum polling attempts.
     *
     * **Polling Behavior:**
     * - The method will make up to 20 attempts to fetch the summary by default.
     * - Each attempt is spaced 500ms apart.
     * - If the summary is not ready after 20 attempts, a BraveSearchError is thrown.
     *
     * **Configuration:**
     * - The number of attempts and the interval between attempts can be configured through the class constructor options.
     */
    private pollForSummary;
    private summarizerSearch;
    private getHeaders;
    private formatOptions;
    private handleApiError;
}
export { BraveSearch, BraveSearchError, type BraveSearchOptions, type ImageSearchOptions, type LocalDescriptionsSearchApiResponse, type LocalPoiSearchApiResponse, type SummarizerOptions, type SummarizerSearchApiResponse, type WebSearchApiResponse, type ImageSearchApiResponse, type NewsSearchApiResponse, type NewsSearchOptions, };