@isdk/web-searcher 0.1.4 → 0.1.6

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import * as _isdk_web_fetcher from '@isdk/web-fetcher';
 import { FetcherOptions, FetchSession } from '@isdk/web-fetcher';
+export { FetcherOptions } from '@isdk/web-fetcher';
 import { IBaseFactoryOptions } from 'custom-factory';
 
 /**
@@ -83,6 +84,12 @@ interface SearchContext {
     page: number;
     /** The requested limit of results. */
     limit?: number;
+    /** Allows for custom variables passed via search options. */
+    [key: string]: any;
+    /** The baseUrl used for this specific fetch (if multi-instance is enabled) */
+    baseUrl?: string;
+    /** The name of the engine executing the search */
+    engine?: string;
 }
 type SearchTimeRangePreset = 'all' | 'hour' | 'day' | 'week' | 'month' | 'year';
 interface CustomTimeRange {
@@ -92,7 +99,7 @@ interface CustomTimeRange {
     to?: Date | string;
 }
 type SearchTimeRange = SearchTimeRangePreset | CustomTimeRange;
-type SearchCategory = 'all' | 'images' | 'videos' | 'news';
+type SearchCategory = 'all' | 'images' | 'videos' | 'news' | string;
 type SafeSearchLevel = 'off' | 'moderate' | 'strict';
 /**
  * Options provided when executing a search.
@@ -139,12 +146,188 @@ interface SearchOptions {
     transform?: (results: StandardSearchResult[], context: SearchContext) => Promise<StandardSearchResult[]> | StandardSearchResult[];
     /** Any other custom variables to be injected into the template. */
     [key: string]: any;
+    /**
+     * Allows the user to dynamically specify or override the base URLs for the engines.
+     * Can be an array of URLs for a single engine, or a map of engine names to URL arrays.
+     */
+    baseUrls?: string[] | Record<string, string[]>;
+    /**
+     * User-defined callback to validate the fetched results for a page.
+     * If it returns false, the fetch is considered a failure, triggering the retry/failover mechanism.
+     */
+    validator?: (results: StandardSearchResult[], context: SearchContext) => boolean | Promise<boolean>;
+    /**
+     * If true (default), the searcher will attempt to fulfill the requested `limit`
+     * by falling back to subsequent engines in the chain if previous ones are exhausted.
+     * If false, it will stop after the first successful engine regardless of whether
+     * the limit was reached.
+     */
+    fillLimit?: boolean;
+    /**
+     * Specifies which page index to start the search from.
+     * Useful when delegating pagination across different sessions.
+     * @default 0
+     */
+    startPage?: number;
+}
+
+/**
+ * Options for network requests.
+ */
+interface FetchExtractorOptions {
+    /** Timeout in milliseconds. Defaults vary by function (5s to 10s). */
+    timeout?: number;
+    /** Custom HTTP headers to include in the request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Fetches only the HTTP headers for a given URL using a HEAD request.
+ * Useful for checking 'last-modified' without downloading the body.
+ *
+ * @param url - The URL to check.
+ * @param options - Request options.
+ * @returns The Headers object, or null on failure.
+ */
+declare function fetchHeaders(url: string, options?: FetchExtractorOptions): Promise<Headers | null>;
+/**
+ * Fetches a partial amount of content from a URL.
+ * Automatically handles character set detection from the Content-Type header.
+ * Aborts the request once the specified maxBytes is reached.
+ *
+ * @param url - The URL to fetch.
+ * @param maxBytes - The maximum number of bytes to read. Defaults to 32KB.
+ * @param options - Request options.
+ * @returns An object containing the decoded content string and the response headers.
+ */
+declare function fetchPartial(url: string, maxBytes?: number, options?: FetchExtractorOptions): Promise<{
+    content: string;
+    headers: Headers;
+} | null>;
+
+/**
+ * Represents structured data extracted from an HTML document.
+ */
+interface HtmlData {
+    /** Map of meta tag names/properties to their content. Keys are lowercase. */
+    meta: Record<string, string>;
+    /** Array of parsed JSON-LD objects found in the document. */
+    jsonLd: any[];
+    /** Array of data from HTML <time> tags. */
+    time: Array<{
+        /** The value of the 'datetime' attribute, if present. */
+        datetime: string | null;
+        /** The text content within the <time> tag, with HTML stripped. */
+        text: string;
+    }>;
 }
+/**
+ * Converts a Web API Headers object into a plain JavaScript record.
+ * All header names are converted to lowercase for consistent access.
+ *
+ * @param headers - The Headers object to parse.
+ * @returns A record where keys are lowercase header names.
+ */
+declare function parseHeaders(headers: Headers): Record<string, string>;
+/**
+
+ * Parses an HTML string to extract generic metadata structures (Meta tags, JSON-LD, Time tags).
+
+ * This function does not perform field-specific logic (like finding a date); it simply
+
+ * collects available structured data.
+
+ *
+
+ * @param html - The raw HTML content to parse.
+
+ * @returns An object containing grouped metadata from the HTML.
+
+ */
+declare function parseHtml(html: string): HtmlData;
+
+/**
+ * Result object for generic metadata extraction.
+ */
+interface MetadataResult {
+    /** The extracted and normalized date, if any. */
+    date?: string | null;
+    /** Placeholders for future metadata fields. */
+    [key: string]: any;
+}
+/**
+ * Supported metadata types for extraction.
+ */
+type MetadataType = 'date' | string;
+/**
+ * Extracts specific metadata from parsed HTML and headers based on a requested type.
+ * Currently supports 'date' extraction with a prioritized fallback mechanism.
+ *
+ * @param result - An object containing the raw HTML content and response headers.
+ * @param type - The type of metadata to extract.
+ * @returns The extracted and normalized value, or null if not found.
+ */
+declare function extractMetadataFrom(result: {
+    content: string;
+    headers: Headers;
+}, type: MetadataType): string | null;
+
+/**
+ * Normalizes a date string into a standard ISO 8601 format (UTC).
+ * It handles various formats (YYYY-MM-DD, RFC2822, etc.) and performs
+ * aggressive cleaning and sanity checks.
+ *
+ * @param dateStr - The raw date string to normalize.
+ * @returns An ISO 8601 string (e.g., "2024-01-20T00:00:00.000Z") or null if invalid.
+ */
+declare function normalizeDate(dateStr: string | null): string | null;
+
+/**
+ * Options for the extractDate function.
+ */
+interface ExtractOptions extends FetchExtractorOptions {
+    /**
+     * Maximum number of bytes to download from the URL.
+     * Defaults to 32768 (32KB), which is usually enough for the HTML <head>.
+     */
+    maxBytes?: number;
+}
+/**
+ * High-level convenience function to extract the publication or modification date from a URL.
+ * It performs a partial fetch of the content and applies multiple extraction rules
+ * (LD+JSON, Meta tags, Time tags, Headers) to find the most reliable date.
+ *
+ * @param url - The web page URL to analyze.
+ * @param options - Fetch and extraction options.
+ * @returns An ISO 8601 date string, or null if no valid date could be found.
+ *
+ * @example
+ * ```ts
+ * const date = await extractDate('https://example.com/article');
+ * console.log(date); // "2024-01-20T12:00:00.000Z"
+ * ```
+ */
+declare function extractDate(url: string, options?: ExtractOptions): Promise<string | null>;
+
+interface VerifiedUrl {
+    url: string;
+    latency: number;
+}
+/**
+ * A general utility to test a list of URLs for availability and latency.
+ * Returns a list of verified URLs sorted by response time.
+ */
+declare function testUrlsByLatency(urls: string[], options?: {
+    timeout?: number;
+    limit?: number;
+    testPath?: string;
+    proxy?: string;
+}): Promise<VerifiedUrl[]>;
 
 /**
  * Constructor definition for Searcher subclasses.
  */
 type SearcherConstructor = new (options?: FetcherOptions) => WebSearcher;
+
 /**
  * The abstract base class for all search engines.
  *
@@ -176,6 +359,23 @@ declare abstract class WebSearcher extends FetchSession {
      * Useful for registering shorthand names (e.g., 'g' for 'Google').
      */
     static alias?: string | string[];
+    /** Default base URLs for engines that support multiple instances. */
+    static defaultBaseUrls?: string[];
+    /** Globally shared index for tracking the currently active instance (node) across sessions. */
+    static currentInstanceIndex?: number;
+    /** @internal */
+    static _defaultOptions?: SearchOptions;
+    /**
+     * Gets or sets the default search parameters for this specific engine class.
+     * This does not include settings from parent classes.
+     */
+    static get defaultOptions(): SearchOptions;
+    static set defaultOptions(options: SearchOptions);
+    /**
+     * Retrieves the combined default search options by traversing the prototype chain.
+     * Priority: Current class > Parent class > WebSearcher base class.
+     */
+    static getDefaultOptions(): SearchOptions;
     /**
      * Registers a search engine class.
      *
@@ -219,23 +419,25 @@ declare abstract class WebSearcher extends FetchSession {
      */
     static setAliases: (ctor: typeof WebSearcher, ...aliases: string[]) => void;
     /**
-     * Static helper to execute a one-off search.
+     * Static helper to execute a one-off search or a fallback chain.
      *
-     * It creates an instance of the specified engine, executes the search, and then
-     * automatically disposes of the session.
+     * It creates an instance of the specified engine(s), executes the search, and automatically
+     * falls back to the next engine in the list if the current one fails or is exhausted.
      *
-     * @param engineName - The name of the engine to use (e.g., 'Google').
+     * @param engineNames - The name(s) of the engine(s) to use (e.g., 'Google' or ['SearXNG', 'Google']).
      * @param query - The search query string.
      * @param options - Combined search options and fetcher options.
      * @returns A promise resolving to an array of standardized search results.
      */
-    static search(engineName: string, query: string, options?: SearchOptions & FetcherOptions): Promise<StandardSearchResult[]>;
+    static search(engineNames: string | string[], query: string, options?: SearchOptions & FetcherOptions): Promise<StandardSearchResult[]>;
     /**
      * The declarative template for the fetch options.
      *
-     * Subclasses **must** implement this getter to provide the engine configuration,
+     * Subclasses can implement this getter to provide the engine configuration,
      * including the base URL, search parameters pattern, and extraction rules.
      *
+     * This getter is **optional** if you override {@link getTemplate}.
+     *
      * Supports variable injection using syntax like `${query}`, `${offset}`, etc.
      *
      * @example
@@ -248,7 +450,7 @@ declare abstract class WebSearcher extends FetchSession {
      * }
      * ```
      */
-    abstract get template(): FetcherOptions;
+    get template(): FetcherOptions;
     /**
      * Optional pagination configuration.
      * Defines how the searcher navigates to subsequent pages.
@@ -256,18 +458,39 @@ declare abstract class WebSearcher extends FetchSession {
      * If undefined, the searcher will only fetch the first page.
      */
     get pagination(): PaginationConfig | undefined;
+    /**
+     * Dynamically retrieves the fetch template based on current variables and search options.
+     *
+     * Subclasses can override this method to return different extraction rules (actions)
+     * or URL patterns based on the search category, region, or other parameters.
+     *
+     * @param variables - The calculated variables (from formatOptions, pagination, etc.).
+     * @param options - The original search options provided by the user.
+     * @returns The fetcher configuration to be used for the current request.
+     */
+    protected getTemplate(variables: Record<string, any>, options: SearchOptions): FetcherOptions;
     protected createContext(options?: FetcherOptions): _isdk_web_fetcher.FetchContext;
     /**
      * Executes a search query.
      *
-     * This method handles the pagination loop, variable injection, fetching,
-     * and result transformation.
+     * This method handles the pagination loop, multi-instance failover, variable injection,
+     * fetching, and result transformation.
      *
      * @param query - The search query string.
      * @param options - Optional search parameters (e.g., limit, timeRange).
      * @returns A promise resolving to an array of standardized search results.
      */
     search(query: string, options?: SearchOptions): Promise<StandardSearchResult[]>;
+    /**
+     * Hook for subclasses to validate fetched results before they are accepted.
+     * If this returns false, the instance manager will consider the fetch a failure
+     * and automatically switch to the next available baseUrl (if any).
+     *
+     * @param results - The extracted results.
+     * @param context - Context including the current baseUrl and page.
+     * @returns A promise resolving to true if valid, false otherwise.
+     */
+    protected validateFetchResult(results: StandardSearchResult[], context: SearchContext): Promise<boolean>;
     /**
      * Transform and clean the raw extracted results.
      *
@@ -347,4 +570,4 @@ declare class GoogleSearcher extends WebSearcher {
     protected transform(outputs: Record<string, any>): Promise<any[]>;
 }
 
-export { type CustomTimeRange, GoogleSearcher, type PaginationConfig, type SafeSearchLevel, type SearchCategory, type SearchContext, type SearchOptions, type SearchTimeRange, type SearchTimeRangePreset, type SearcherConstructor, type StandardSearchResult, WebSearcher };
+export { type CustomTimeRange, type ExtractOptions, type FetchExtractorOptions, GoogleSearcher, type HtmlData, type MetadataResult, type MetadataType, type PaginationConfig, type SafeSearchLevel, type SearchCategory, type SearchContext, type SearchOptions, type SearchTimeRange, type SearchTimeRangePreset, type SearcherConstructor, type StandardSearchResult, type VerifiedUrl, WebSearcher, extractDate, extractMetadataFrom, fetchHeaders, fetchPartial, normalizeDate, parseHeaders, parseHtml, testUrlsByLatency };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _isdk_web_fetcher from '@isdk/web-fetcher';
 import { FetcherOptions, FetchSession } from '@isdk/web-fetcher';
+export { FetcherOptions } from '@isdk/web-fetcher';
 import { IBaseFactoryOptions } from 'custom-factory';
 
 /**
@@ -83,6 +84,12 @@ interface SearchContext {
     page: number;
     /** The requested limit of results. */
     limit?: number;
+    /** Allows for custom variables passed via search options. */
+    [key: string]: any;
+    /** The baseUrl used for this specific fetch (if multi-instance is enabled) */
+    baseUrl?: string;
+    /** The name of the engine executing the search */
+    engine?: string;
 }
 type SearchTimeRangePreset = 'all' | 'hour' | 'day' | 'week' | 'month' | 'year';
 interface CustomTimeRange {
@@ -92,7 +99,7 @@ interface CustomTimeRange {
     to?: Date | string;
 }
 type SearchTimeRange = SearchTimeRangePreset | CustomTimeRange;
-type SearchCategory = 'all' | 'images' | 'videos' | 'news';
+type SearchCategory = 'all' | 'images' | 'videos' | 'news' | string;
 type SafeSearchLevel = 'off' | 'moderate' | 'strict';
 /**
  * Options provided when executing a search.
@@ -139,12 +146,188 @@ interface SearchOptions {
     transform?: (results: StandardSearchResult[], context: SearchContext) => Promise<StandardSearchResult[]> | StandardSearchResult[];
     /** Any other custom variables to be injected into the template. */
     [key: string]: any;
+    /**
+     * Allows the user to dynamically specify or override the base URLs for the engines.
+     * Can be an array of URLs for a single engine, or a map of engine names to URL arrays.
+     */
+    baseUrls?: string[] | Record<string, string[]>;
+    /**
+     * User-defined callback to validate the fetched results for a page.
+     * If it returns false, the fetch is considered a failure, triggering the retry/failover mechanism.
+     */
+    validator?: (results: StandardSearchResult[], context: SearchContext) => boolean | Promise<boolean>;
+    /**
+     * If true (default), the searcher will attempt to fulfill the requested `limit`
+     * by falling back to subsequent engines in the chain if previous ones are exhausted.
+     * If false, it will stop after the first successful engine regardless of whether
+     * the limit was reached.
+     */
+    fillLimit?: boolean;
+    /**
+     * Specifies which page index to start the search from.
+     * Useful when delegating pagination across different sessions.
+     * @default 0
+     */
+    startPage?: number;
+}
+
+/**
+ * Options for network requests.
+ */
+interface FetchExtractorOptions {
+    /** Timeout in milliseconds. Defaults vary by function (5s to 10s). */
+    timeout?: number;
+    /** Custom HTTP headers to include in the request. */
+    headers?: Record<string, string>;
+}
+/**
+ * Fetches only the HTTP headers for a given URL using a HEAD request.
+ * Useful for checking 'last-modified' without downloading the body.
+ *
+ * @param url - The URL to check.
+ * @param options - Request options.
+ * @returns The Headers object, or null on failure.
+ */
+declare function fetchHeaders(url: string, options?: FetchExtractorOptions): Promise<Headers | null>;
+/**
+ * Fetches a partial amount of content from a URL.
+ * Automatically handles character set detection from the Content-Type header.
+ * Aborts the request once the specified maxBytes is reached.
+ *
+ * @param url - The URL to fetch.
+ * @param maxBytes - The maximum number of bytes to read. Defaults to 32KB.
+ * @param options - Request options.
+ * @returns An object containing the decoded content string and the response headers.
+ */
+declare function fetchPartial(url: string, maxBytes?: number, options?: FetchExtractorOptions): Promise<{
+    content: string;
+    headers: Headers;
+} | null>;
+
+/**
+ * Represents structured data extracted from an HTML document.
+ */
+interface HtmlData {
+    /** Map of meta tag names/properties to their content. Keys are lowercase. */
+    meta: Record<string, string>;
+    /** Array of parsed JSON-LD objects found in the document. */
+    jsonLd: any[];
+    /** Array of data from HTML <time> tags. */
+    time: Array<{
+        /** The value of the 'datetime' attribute, if present. */
+        datetime: string | null;
+        /** The text content within the <time> tag, with HTML stripped. */
+        text: string;
+    }>;
 }
+/**
+ * Converts a Web API Headers object into a plain JavaScript record.
+ * All header names are converted to lowercase for consistent access.
+ *
+ * @param headers - The Headers object to parse.
+ * @returns A record where keys are lowercase header names.
+ */
+declare function parseHeaders(headers: Headers): Record<string, string>;
+/**
+
+ * Parses an HTML string to extract generic metadata structures (Meta tags, JSON-LD, Time tags).
+
+ * This function does not perform field-specific logic (like finding a date); it simply
+
+ * collects available structured data.
+
+ *
+
+ * @param html - The raw HTML content to parse.
+
+ * @returns An object containing grouped metadata from the HTML.
+
+ */
+declare function parseHtml(html: string): HtmlData;
+
+/**
+ * Result object for generic metadata extraction.
+ */
+interface MetadataResult {
+    /** The extracted and normalized date, if any. */
+    date?: string | null;
+    /** Placeholders for future metadata fields. */
+    [key: string]: any;
+}
+/**
+ * Supported metadata types for extraction.
+ */
+type MetadataType = 'date' | string;
+/**
+ * Extracts specific metadata from parsed HTML and headers based on a requested type.
+ * Currently supports 'date' extraction with a prioritized fallback mechanism.
+ *
+ * @param result - An object containing the raw HTML content and response headers.
+ * @param type - The type of metadata to extract.
+ * @returns The extracted and normalized value, or null if not found.
+ */
+declare function extractMetadataFrom(result: {
+    content: string;
+    headers: Headers;
+}, type: MetadataType): string | null;
+
+/**
+ * Normalizes a date string into a standard ISO 8601 format (UTC).
+ * It handles various formats (YYYY-MM-DD, RFC2822, etc.) and performs
+ * aggressive cleaning and sanity checks.
+ *
+ * @param dateStr - The raw date string to normalize.
+ * @returns An ISO 8601 string (e.g., "2024-01-20T00:00:00.000Z") or null if invalid.
+ */
+declare function normalizeDate(dateStr: string | null): string | null;
+
+/**
+ * Options for the extractDate function.
+ */
+interface ExtractOptions extends FetchExtractorOptions {
+    /**
+     * Maximum number of bytes to download from the URL.
+     * Defaults to 32768 (32KB), which is usually enough for the HTML <head>.
+     */
+    maxBytes?: number;
+}
+/**
+ * High-level convenience function to extract the publication or modification date from a URL.
+ * It performs a partial fetch of the content and applies multiple extraction rules
+ * (LD+JSON, Meta tags, Time tags, Headers) to find the most reliable date.
+ *
+ * @param url - The web page URL to analyze.
+ * @param options - Fetch and extraction options.
+ * @returns An ISO 8601 date string, or null if no valid date could be found.
+ *
+ * @example
+ * ```ts
+ * const date = await extractDate('https://example.com/article');
+ * console.log(date); // "2024-01-20T12:00:00.000Z"
+ * ```
+ */
+declare function extractDate(url: string, options?: ExtractOptions): Promise<string | null>;
+
+interface VerifiedUrl {
+    url: string;
+    latency: number;
+}
+/**
+ * A general utility to test a list of URLs for availability and latency.
+ * Returns a list of verified URLs sorted by response time.
+ */
+declare function testUrlsByLatency(urls: string[], options?: {
+    timeout?: number;
+    limit?: number;
+    testPath?: string;
+    proxy?: string;
+}): Promise<VerifiedUrl[]>;
 
 /**
  * Constructor definition for Searcher subclasses.
  */
 type SearcherConstructor = new (options?: FetcherOptions) => WebSearcher;
+
 /**
  * The abstract base class for all search engines.
  *
@@ -176,6 +359,23 @@ declare abstract class WebSearcher extends FetchSession {
      * Useful for registering shorthand names (e.g., 'g' for 'Google').
      */
     static alias?: string | string[];
+    /** Default base URLs for engines that support multiple instances. */
+    static defaultBaseUrls?: string[];
+    /** Globally shared index for tracking the currently active instance (node) across sessions. */
+    static currentInstanceIndex?: number;
+    /** @internal */
+    static _defaultOptions?: SearchOptions;
+    /**
+     * Gets or sets the default search parameters for this specific engine class.
+     * This does not include settings from parent classes.
+     */
+    static get defaultOptions(): SearchOptions;
+    static set defaultOptions(options: SearchOptions);
+    /**
+     * Retrieves the combined default search options by traversing the prototype chain.
+     * Priority: Current class > Parent class > WebSearcher base class.
+     */
+    static getDefaultOptions(): SearchOptions;
     /**
      * Registers a search engine class.
      *
@@ -219,23 +419,25 @@ declare abstract class WebSearcher extends FetchSession {
      */
     static setAliases: (ctor: typeof WebSearcher, ...aliases: string[]) => void;
     /**
-     * Static helper to execute a one-off search.
+     * Static helper to execute a one-off search or a fallback chain.
      *
-     * It creates an instance of the specified engine, executes the search, and then
-     * automatically disposes of the session.
+     * It creates an instance of the specified engine(s), executes the search, and automatically
+     * falls back to the next engine in the list if the current one fails or is exhausted.
      *
-     * @param engineName - The name of the engine to use (e.g., 'Google').
+     * @param engineNames - The name(s) of the engine(s) to use (e.g., 'Google' or ['SearXNG', 'Google']).
      * @param query - The search query string.
      * @param options - Combined search options and fetcher options.
      * @returns A promise resolving to an array of standardized search results.
      */
-    static search(engineName: string, query: string, options?: SearchOptions & FetcherOptions): Promise<StandardSearchResult[]>;
+    static search(engineNames: string | string[], query: string, options?: SearchOptions & FetcherOptions): Promise<StandardSearchResult[]>;
     /**
      * The declarative template for the fetch options.
      *
-     * Subclasses **must** implement this getter to provide the engine configuration,
+     * Subclasses can implement this getter to provide the engine configuration,
      * including the base URL, search parameters pattern, and extraction rules.
      *
+     * This getter is **optional** if you override {@link getTemplate}.
+     *
      * Supports variable injection using syntax like `${query}`, `${offset}`, etc.
      *
      * @example
@@ -248,7 +450,7 @@ declare abstract class WebSearcher extends FetchSession {
      * }
      * ```
      */
-    abstract get template(): FetcherOptions;
+    get template(): FetcherOptions;
     /**
      * Optional pagination configuration.
      * Defines how the searcher navigates to subsequent pages.
@@ -256,18 +458,39 @@ declare abstract class WebSearcher extends FetchSession {
      * If undefined, the searcher will only fetch the first page.
      */
     get pagination(): PaginationConfig | undefined;
+    /**
+     * Dynamically retrieves the fetch template based on current variables and search options.
+     *
+     * Subclasses can override this method to return different extraction rules (actions)
+     * or URL patterns based on the search category, region, or other parameters.
+     *
+     * @param variables - The calculated variables (from formatOptions, pagination, etc.).
+     * @param options - The original search options provided by the user.
+     * @returns The fetcher configuration to be used for the current request.
+     */
+    protected getTemplate(variables: Record<string, any>, options: SearchOptions): FetcherOptions;
     protected createContext(options?: FetcherOptions): _isdk_web_fetcher.FetchContext;
     /**
      * Executes a search query.
      *
-     * This method handles the pagination loop, variable injection, fetching,
-     * and result transformation.
+     * This method handles the pagination loop, multi-instance failover, variable injection,
+     * fetching, and result transformation.
      *
      * @param query - The search query string.
      * @param options - Optional search parameters (e.g., limit, timeRange).
      * @returns A promise resolving to an array of standardized search results.
      */
     search(query: string, options?: SearchOptions): Promise<StandardSearchResult[]>;
+    /**
+     * Hook for subclasses to validate fetched results before they are accepted.
+     * If this returns false, the instance manager will consider the fetch a failure
+     * and automatically switch to the next available baseUrl (if any).
+     *
+     * @param results - The extracted results.
+     * @param context - Context including the current baseUrl and page.
+     * @returns A promise resolving to true if valid, false otherwise.
+     */
+    protected validateFetchResult(results: StandardSearchResult[], context: SearchContext): Promise<boolean>;
     /**
      * Transform and clean the raw extracted results.
      *
@@ -347,4 +570,4 @@ declare class GoogleSearcher extends WebSearcher {
     protected transform(outputs: Record<string, any>): Promise<any[]>;
 }
 
-export { type CustomTimeRange, GoogleSearcher, type PaginationConfig, type SafeSearchLevel, type SearchCategory, type SearchContext, type SearchOptions, type SearchTimeRange, type SearchTimeRangePreset, type SearcherConstructor, type StandardSearchResult, WebSearcher };
+export { type CustomTimeRange, type ExtractOptions, type FetchExtractorOptions, GoogleSearcher, type HtmlData, type MetadataResult, type MetadataType, type PaginationConfig, type SafeSearchLevel, type SearchCategory, type SearchContext, type SearchOptions, type SearchTimeRange, type SearchTimeRangePreset, type SearcherConstructor, type StandardSearchResult, type VerifiedUrl, WebSearcher, extractDate, extractMetadataFrom, fetchHeaders, fetchPartial, normalizeDate, parseHeaders, parseHtml, testUrlsByLatency };