@microsoft/webiq 0.0.1-alpha.2 → 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1103 @@
+/** Authentication providers for Web IQ SDK. */
+/** Default OAuth scope for the Web IQ API. */
+declare const DEFAULT_SCOPE = "https://api.microsoft.ai/.default";
+/** Minimal `TokenCredential` shape compatible with `@azure/identity`. */
+interface TokenCredential {
+    getToken(scopes: string | string[], options?: Record<string, unknown>): Promise<{
+        token: string;
+        expiresOnTimestamp?: number;
+    } | null>;
+}
+/** Base interface for authentication providers. */
+interface AuthProvider {
+    getHeaders(): Promise<Record<string, string>>;
+}
+/** API key authentication via the `x-apikey` header. */
+declare class ApiKeyAuth implements AuthProvider {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    getHeaders(): Promise<Record<string, string>>;
+}
+/** Bearer-token authentication via an azure-identity `TokenCredential`. */
+declare class EntraIDAuth implements AuthProvider {
+    private readonly credential;
+    private readonly scope;
+    constructor(credential: TokenCredential, options?: {
+        scope?: string;
+    });
+    getHeaders(): Promise<Record<string, string>>;
+}
+/** Create an `AuthProvider` from an API key or a `TokenCredential`. */
+declare function createAuth(options: {
+    apiKey?: string;
+    credential?: TokenCredential;
+    scope?: string;
+}): AuthProvider;
+
+/**
+ * Base transport interfaces.
+ */
+/** Default request timeout in milliseconds. */
+declare const DEFAULT_TIMEOUT = 10000;
+/**
+ * Custom fetch function type.
+ *
+ * Defined as a structural call signature rather than `typeof fetch` so that
+ * consumers are not required to have `lib.dom` or a specific global `fetch`
+ * typing in their `tsconfig`.  The loose `Record<string, unknown>` on the
+ * init parameter allows runtime-specific extensions (e.g. undici's
+ * `dispatcher` option) without requiring a type assertion.
+ */
+type FetchFunction = (input: string | URL | Request, init?: RequestInit & Record<string, unknown>) => Promise<Response>;
+/**
+ * Request options for transport layer.
+ */
+interface TransportRequestOptions {
+    method: string;
+    path: string;
+    json?: Record<string, unknown>;
+    /** Per-request timeout override in milliseconds. */
+    timeout?: number;
+    /**
+     * Caller-provided cancellation signal. When the signal aborts, the in-flight
+     * request is cancelled and the signal's `reason` is re-thrown (no retry, no
+     * `APIConnectionError` wrapping). Combine with `AbortSignal.timeout(ms)` for
+     * a wall-clock cap, or pass `req.signal` from an HTTP framework to propagate
+     * client disconnects.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Base interface for transports.
+ */
+interface Transport {
+    /** Make an API request. */
+    request<T = unknown>(options: TransportRequestOptions): Promise<T>;
+    /** Close the transport and release resources. */
+    close(): Promise<void>;
+}
+
+declare enum ContentFormat {
+    PASSAGE = "passage",
+    TEXT = "text",
+    HTML = "html",
+    MARKDOWN = "markdown"
+}
+
+type WebResult = {
+    /**
+     * The title of the webpage.
+     */
+    title?: string | null;
+    /**
+     * The source URL of the webpage.
+     */
+    url?: string | null;
+    /**
+     * The detailed content of the webpage.
+     */
+    content?: string | null;
+    /**
+     * The last updated date of the webpage, follows ISO8601 format.
+     */
+    lastUpdatedAt?: string | null;
+    /**
+     * The last crawled date of the webpage, follows ISO8601 format.
+     */
+    crawledAt?: string | null;
+    /**
+     * The language of the webpage, uses ISO 639-1 language code.
+     */
+    language?: string | null;
+    /**
+     * Indicates whether the result includes adult content.
+     */
+    isAdult?: boolean;
+};
+
+type WebResponse = {
+    /**
+     * List of web page results.
+     */
+    webResults?: Array<WebResult> | null;
+    /**
+     * Trace ID for debugging and tracking.
+     */
+    traceId?: string | null;
+};
+
+/**
+ * Web search resource.
+ */
+
+/**
+ * Web search request parameters.
+ */
+interface WebSearchParams {
+    /** Search query string (1-1000 chars). */
+    query: string;
+    /** Max results to return (1-50, default 10). */
+    maxResults?: number;
+    /** 2-letter ISO 639-1 language code. */
+    language?: string;
+    /** 2-letter country/region code. */
+    region?: string;
+    /** Location in format 'lat:<float>;long:<float>'. */
+    location?: string;
+    /** Content format: use ContentFormat.PASSAGE, .TEXT, .HTML, or .MARKDOWN. */
+    contentFormat?: ContentFormat;
+    /** Max characters in content (1-500000, default 10000). */
+    maxLength?: number;
+    /** Per-request timeout in milliseconds (overrides client default). */
+    timeout?: number;
+    /**
+     * Caller-provided cancellation signal. Aborts the in-flight request when
+     * fired; the signal's `reason` is re-thrown unchanged. Combine with
+     * `AbortSignal.timeout(ms)` for a wall-clock budget that includes retries,
+     * or pass `req.signal` from your HTTP framework to propagate client
+     * disconnects.
+     */
+    signal?: AbortSignal;
+}
+/** Web search options (query is passed separately). */
+type WebSearchOptions = Omit<WebSearchParams, 'query'>;
+/**
+ * Web search resource for the Web IQ API.
+ */
+declare class WebResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Search the web for relevant content.
+     *
+     * @param query - Search query string (1-1000 chars)
+     * @param options - Search options
+     * @returns WebResponse with webResults list and traceId
+     */
+    search(query: string, options?: WebSearchOptions): Promise<WebResponse>;
+}
+
+type NewsThumbnail = {
+    /**
+     * The URL of the thumbnail.
+     */
+    url?: string | null;
+    /**
+     * Width of the thumbnail, in pixels.
+     */
+    width?: number;
+    /**
+     * Height of the thumbnail, in pixels.
+     */
+    height?: number;
+};
+
+type NewsItem = {
+    /**
+     * The title of the news.
+     */
+    title?: string | null;
+    /**
+     * The source URL of the news.
+     */
+    url?: string | null;
+    /**
+     * The detailed content of the news.
+     */
+    content?: string | null;
+    /**
+     * A snippet from the news content.
+     */
+    snippet?: string | null;
+    thumbnail?: NewsThumbnail;
+    /**
+     * The last updated date of the news, in UTC ISO8601 format.
+     */
+    lastUpdatedAt?: string | null;
+    /**
+     * Publisher name, such as 'USA TODAY | MSN', 'CNN', etc.
+     */
+    source?: string | null;
+    /**
+     * Indicates if the content is adult content.
+     */
+    isAdult?: boolean;
+};
+
+type NewsResponse = {
+    /**
+     * List of news article results.
+     */
+    newsResults?: Array<NewsItem> | null;
+    /**
+     * Trace ID for debugging and tracking.
+     */
+    traceId?: string | null;
+};
+
+/**
+ * News search resource.
+ */
+
+/**
+ * News search request parameters.
+ */
+interface NewsSearchParams {
+    /** Search query string (1-1000 chars). */
+    query: string;
+    /** Max results to return (1-20, default 10). */
+    maxResults?: number;
+    /** 2-letter ISO 639-1 language code. */
+    language?: string;
+    /** 2-letter country/region code. */
+    region?: string;
+    /** Location in format 'lat:<float>;long:<float>'. */
+    location?: string;
+    /** Content format: use ContentFormat.PASSAGE, .TEXT, .HTML, or .MARKDOWN. */
+    contentFormat?: ContentFormat;
+    /** Max characters in content (1-500000, default 10000). */
+    maxLength?: number;
+    /** Per-request timeout in milliseconds (overrides client default). */
+    timeout?: number;
+    /** Caller-provided cancellation signal (see `WebSearchParams.signal`). */
+    signal?: AbortSignal;
+}
+/** News search options (query is passed separately). */
+type NewsSearchOptions = Omit<NewsSearchParams, 'query'>;
+/**
+ * News search resource for the Web IQ API.
+ */
+declare class NewsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Search for news articles.
+     *
+     * @param query - Search query string (1-1000 chars)
+     * @param options - Search options
+     * @returns NewsResponse with newsResults list and traceId
+     */
+    search(query: string, options?: NewsSearchOptions): Promise<NewsResponse>;
+}
+
+declare enum SafeSearch {
+    OFF = "off",
+    STRICT = "strict"
+}
+
+declare enum VideoDuration {
+    SHORT = "short",
+    MEDIUM = "medium",
+    LONG = "long"
+}
+
+declare enum VideoResolution {
+    _360P = "360p",
+    _480P = "480p",
+    _720P = "720p",
+    _1080P = "1080p"
+}
+
+type PlaylistVideo = {
+    /**
+     * Title of the video.
+     */
+    title?: string | null;
+    /**
+     * Description of the video.
+     */
+    description?: string | null;
+    /**
+     * URL of the video.
+     */
+    url?: string | null;
+};
+
+type PlaylistItem = {
+    /**
+     * Title of the playlist.
+     */
+    title?: string | null;
+    /**
+     * Description of the playlist.
+     */
+    description?: string | null;
+    /**
+     * Array of videos in the playlist.
+     */
+    videos?: Array<PlaylistVideo> | null;
+};
+
+type VideoMoment = {
+    /**
+     * Title of the moment segment.
+     */
+    title?: string | null;
+    /**
+     * Description of what happens in this moment.
+     */
+    description?: string | null;
+    /**
+     * Start time of the moment in format 'd.hh:mm:ss'.
+     */
+    startTime?: string | null;
+    /**
+     * End time of the moment in format 'd.hh:mm:ss'.
+     */
+    endTime?: string | null;
+    /**
+     * Direct URL to this specific moment in the video.
+     */
+    momentUrl?: string | null;
+};
+
+type VideoItem = {
+    /**
+     * The title or name of the video.
+     */
+    title?: string | null;
+    /**
+     * The video source URL.
+     */
+    url?: string | null;
+    /**
+     * Description of the video content. This is either given by video uploader or generated by LLM
+     */
+    description?: string | null;
+    /**
+     * Uploader or publisher of the video.
+     */
+    publishedBy?: string | null;
+    /**
+     * The number of views the video has.
+     */
+    viewCount?: number;
+    /**
+     * Short summary or highlight of the video.
+     */
+    summary?: string | null;
+    /**
+     * The length of the video in HH:MM:SS format.
+     */
+    length?: string | null;
+    /**
+     * Whether HTTPS embedding is allowed.
+     */
+    allowHttpsEmbedding?: boolean;
+    /**
+     * Whether mobile embedding is allowed.
+     */
+    allowMobileEmbedding?: boolean;
+    /**
+     * URL for embedding the video.
+     */
+    embeddingUrl?: string | null;
+    /**
+     * The last updated date as a formatted string.
+     */
+    lastUpdatedAt?: string | null;
+    /**
+     * Index of the best moment or highlight in the video.
+     */
+    bestMomentIndex?: number | null;
+    /**
+     * Array of video segments/moments.
+     */
+    moments?: Array<VideoMoment> | null;
+    /**
+     * Thumbnail URL of the video.
+     */
+    thumbnailUrl?: string | null;
+    /**
+     * The width of the video in pixels.
+     */
+    width?: number | null;
+    /**
+     * The height of the video in pixels.
+     */
+    height?: number | null;
+    /**
+     * Indicates whether the result includes adult content.
+     */
+    isAdult?: boolean;
+};
+
+type VideosResponse = {
+    /**
+     * List of video results.
+     */
+    videoResults?: Array<VideoItem> | null;
+    /**
+     * List of playlist results.
+     */
+    playlists?: Array<PlaylistItem> | null;
+    /**
+     * Trace ID for debugging and tracking.
+     */
+    traceId?: string | null;
+};
+
+/**
+ * Videos search resource.
+ */
+
+/**
+ * Videos search request parameters.
+ */
+interface VideosSearchParams {
+    /** Search query string (1-1000 chars). */
+    query: string;
+    /** Max results to return (1-30, default 30). */
+    maxResults?: number;
+    /** 2-letter ISO 639-1 language code. */
+    language?: string;
+    /** 2-letter country/region code. */
+    region?: string;
+    /** Whether to include playlist results (default false). */
+    enablePlaylist?: boolean;
+    /** Time range filter ('day', 'week', 'month', 'year', or date range). */
+    freshness?: string;
+    /** Filter videos by embedding capabilities (e.g. ['player']). */
+    embeddable?: string[];
+    /** Filter by minimum resolution ('360p', '480p', '720p', '1080p'). */
+    resolution?: VideoResolution;
+    /** Safe search filter level. */
+    safeSearch?: SafeSearch;
+    /** Filter by duration ('short' < 5min, 'medium' 5-20min, 'long' > 20min). */
+    duration?: VideoDuration;
+    /** Per-request timeout in milliseconds (overrides client default). */
+    timeout?: number;
+    /** Caller-provided cancellation signal (see `WebSearchParams.signal`). */
+    signal?: AbortSignal;
+}
+/** Videos search options (query is passed separately). */
+type VideoSearchOptions = Omit<VideosSearchParams, 'query'>;
+/**
+ * Videos search resource for the Web IQ API.
+ */
+declare class VideosResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Search for videos.
+     *
+     * @param query - Search query string (1-1000 chars)
+     * @param options - Search options
+     * @returns VideosResponse with videoResults, playlists, and traceId
+     */
+    search(query: string, options?: VideoSearchOptions): Promise<VideosResponse>;
+}
+
+declare enum ImageAspectRatio {
+    SQUARE = "square",
+    WIDE = "wide",
+    TALL = "tall"
+}
+
+declare enum ImageColor {
+    COLOR_ONLY = "colorOnly",
+    MONOCHROME = "monochrome"
+}
+
+declare enum ImageSize {
+    SMALL = "small",
+    MEDIUM = "medium",
+    LARGE = "large",
+    EXTRA_LARGE = "extraLarge"
+}
+
+type ImageItem = {
+    /**
+     * The title of the image.
+     */
+    title?: string | null;
+    /**
+     * The source URL of the image.
+     */
+    url?: string | null;
+    /**
+     * The host page URL of the image.
+     */
+    hostPageUrl?: string | null;
+    /**
+     * Generated description of the image.
+     */
+    caption?: string | null;
+    /**
+     * The width of the image, in pixels.
+     */
+    width?: number;
+    /**
+     * The height of the image, in pixels.
+     */
+    height?: number;
+    /**
+     * The thumbnail source URL of the image.
+     */
+    thumbnailUrl?: string | null;
+    /**
+     * The last updated date of the image, follows ISO8601 format.
+     */
+    lastUpdatedAt?: string | null;
+    /**
+     * Indicates whether the content is adult content.
+     */
+    isAdult?: boolean;
+};
+
+type ImagesResponse = {
+    /**
+     * List of image results.
+     */
+    imageResults?: Array<ImageItem> | null;
+    /**
+     * Trace ID for debugging and tracking.
+     */
+    traceId?: string | null;
+};
+
+/**
+ * Images search resource.
+ */
+
+/**
+ * Images search request parameters.
+ */
+interface ImagesSearchParams {
+    /** Search query string (1-1000 chars). */
+    query: string;
+    /** Max results to return (1-30, default 30). */
+    maxResults?: number;
+    /** 2-letter ISO 639-1 language code. */
+    language?: string;
+    /** 2-letter country/region code. */
+    region?: string;
+    /** Filter by image aspect ratio. */
+    aspectRatio?: ImageAspectRatio;
+    /** Filter by image color type. */
+    color?: ImageColor;
+    /** Safe search filter level. */
+    safeSearch?: SafeSearch;
+    /** Filter by image size. */
+    imageSize?: ImageSize;
+    /** Whether to filter out watermarked images (default false). */
+    watermarkFree?: boolean;
+    /** Maximum height of the image in pixels. */
+    maxHeight?: number;
+    /** Minimum height of the image in pixels. */
+    minHeight?: number;
+    /** Maximum width of the image in pixels. */
+    maxWidth?: number;
+    /** Minimum width of the image in pixels. */
+    minWidth?: number;
+    /** Per-request timeout in milliseconds (overrides client default). */
+    timeout?: number;
+    /** Caller-provided cancellation signal (see `WebSearchParams.signal`). */
+    signal?: AbortSignal;
+}
+/** Images search options (query is passed separately). */
+type ImageSearchOptions = Omit<ImagesSearchParams, 'query'>;
+/**
+ * Images search resource for the Web IQ API.
+ */
+declare class ImagesResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Search for images.
+     *
+     * @param query - Search query string (1-1000 chars)
+     * @param options - Search options
+     * @returns ImagesResponse with imageResults and traceId
+     */
+    search(query: string, options?: ImageSearchOptions): Promise<ImagesResponse>;
+}
+
+declare enum BrowseContentFormat {
+    TEXT = "text",
+    HTML = "html",
+    MARKDOWN = "markdown"
+}
+
+type BrowseResponse = {
+    /**
+     * The URL of the web page.
+     */
+    url?: string | null;
+    /**
+     * The title of the web page.
+     */
+    title?: string | null;
+    /**
+     * The extracted content of the web page.
+     */
+    content?: string | null;
+    /**
+     * Indicates if the content is adult content.
+     */
+    isAdult?: boolean | null;
+    /**
+     * The last updated date of the webpage, follows ISO8601 format.
+     */
+    lastUpdatedAt?: string | null;
+    /**
+     * The last crawled date of the webpage, follows ISO8601 format.
+     */
+    crawledAt?: string | null;
+    /**
+     * Retry after value when on-demand crawl is in progress. Only present when the page needs to be crawled.
+     */
+    retryAfter?: string | null;
+    /**
+     * Trace ID for debugging and tracking.
+     */
+    traceId?: string | null;
+};
+
+/**
+ * Browse resource for fetching web page content.
+ */
+
+/**
+ * Browse request parameters.
+ */
+interface BrowseParams {
+    /** The URL of the web page to browse. */
+    url: string;
+    /** Max characters in content (1-500000, default 10000). */
+    maxLength?: number;
+    /** Crawl behavior ('none', 'fallback', or 'force', default 'none'). */
+    liveCrawl?: 'none' | 'fallback' | 'force';
+    /** Include outbound hyperlinks (default false). */
+    includeWebLinks?: boolean;
+    /** Enable JS rendering for dynamic content (default false). */
+    renderDynamicPages?: boolean;
+    /** Include image URLs (default false). */
+    includeImageLinks?: boolean;
+    /** 2-letter ISO 639-1 language code. */
+    language?: string;
+    /** 2-letter country/region code. */
+    region?: string;
+    /** Content format: use BrowseContentFormat.TEXT, .HTML, or .MARKDOWN. */
+    contentFormat?: BrowseContentFormat;
+    /** Per-request timeout in milliseconds (overrides client default). */
+    timeout?: number;
+    /** Caller-provided cancellation signal (see `WebSearchParams.signal`). */
+    signal?: AbortSignal;
+}
+/** Browse fetch options (url is passed separately). */
+type BrowseFetchOptions = Omit<BrowseParams, 'url'>;
+/**
+ * Browse resource for the Web IQ API.
+ */
+declare class BrowseResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Fetch and extract content from a web page.
+     *
+     * @param url - The URL of the web page to browse
+     * @param options - Fetch options
+     * @returns BrowseResponse with url, content, traceId, and optional retryAfter
+     */
+    fetch(url: string, options?: BrowseFetchOptions): Promise<BrowseResponse>;
+}
+
+declare enum SafeSearchMode {
+    OFF = "off",
+    MODERATE = "moderate",
+    STRICT = "strict"
+}
+
+type QuerySignals = {
+    /**
+     * The original user query as received by the system.
+     */
+    originalQuery?: string | null;
+    /**
+     * The normalized version of the user query after processing (e.g., lowercasing, removing stop words).
+     */
+    normalizedQuery?: string | null;
+    /**
+     * Indicates whether the query is defensive
+     */
+    isDefensive?: boolean | null;
+    /**
+     * Indicates whether the query is flagged as adult query
+     */
+    isAdult?: boolean | null;
+    /**
+     * Indicates whether the query is navigational
+     */
+    isNav?: boolean | null;
+    /**
+     * Indicates whether the query is fresh
+     */
+    isFresh?: boolean | null;
+};
+
+/**
+ * Response for the classic search endpoint. The spec defines this as an
+ * open object (additionalProperties: {}) — keep the typed fields the spec
+ * lists but allow arbitrary extra keys (webResults, imageResults, etc.)
+ * so callers can read what the server actually returns.
+ */
+type SearchClassicResponse = {
+    querySignals?: QuerySignals;
+    /** Trace ID for debugging and tracking. */
+    traceId?: string;
+    [key: string]: any;
+};
+
+/**
+ * Classic search resource.
+ */
+
+/**
+ * Classic search request parameters.
+ */
+interface ClassicSearchParams {
+    /** Search query string (1-1000 chars). */
+    query: string;
+    /** Max answer types to return (1-6, default 6). */
+    maxAnswerTypes?: number;
+    /** Language code (ISO 639-1/2 or BCP 47). */
+    language?: string;
+    /** 2-letter country/region code. */
+    region?: string;
+    /** Location in format 'lat:<float>;long:<float>'. */
+    location?: string;
+    /** Max web results to return (1-50, default 10). */
+    maxResultsWeb?: number;
+    /** Max characters in content (1-500000, default 10000). */
+    maxLength?: number;
+    /** Content format: use ContentFormat.PASSAGE, .TEXT, .HTML, or .MARKDOWN. */
+    contentFormat?: ContentFormat;
+    /** Time range filter ('day', 'week', 'month', 'year', or date range). */
+    freshness?: string;
+    /** List of answer types to include in response. */
+    responseFilter?: string[];
+    /** Safe search mode: use SafeSearchMode.OFF, .MODERATE, or .STRICT. */
+    safeSearch?: SafeSearchMode;
+    /** Per-request timeout in milliseconds (overrides client default). */
+    timeout?: number;
+    /** Caller-provided cancellation signal (see `WebSearchParams.signal`). */
+    signal?: AbortSignal;
+}
+/** Classic search options (query is passed separately). */
+type ClassicSearchOptions = Omit<ClassicSearchParams, 'query'>;
+/**
+ * Classic search resource for the Web IQ API.
+ * Given a query, searches and retrieves content from webpages, images, videos,
+ * news, weather, sports, etc.
+ */
+declare class ClassicResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Perform a classic search returning grouped results across multiple answer types.
+     *
+     * @param query - Search query string (1-1000 chars)
+     * @param options - Search options
+     * @returns SearchClassicResponse with querySignals, traceId, and additional answer types
+     */
+    search(query: string, options?: ClassicSearchOptions): Promise<SearchClassicResponse>;
+}
+
+/**
+ * Configuration for request retry behavior.
+ */
+interface RetryPolicyOptions {
+    /** Maximum number of retry attempts (default: 2) */
+    maxRetries?: number;
+    /** Base delay in seconds for exponential backoff (default: 0.25) */
+    baseDelaySeconds?: number;
+    /** Maximum delay in seconds (default: 4.0) */
+    maxDelaySeconds?: number;
+    /**
+     * HTTP status codes that trigger a retry. 429 and 430 (rate-limit /
+     * concurrency-limit) are intentionally excluded: the transport throws
+     * `RateLimitError` immediately so the caller can inspect `error.retryAfter`
+     * and decide whether to back off.
+     */
+    retryOnStatus?: number[];
+}
+/**
+ * Retry policy with exponential backoff.
+ */
+declare class RetryPolicy {
+    readonly maxRetries: number;
+    readonly baseDelaySeconds: number;
+    readonly maxDelaySeconds: number;
+    readonly retryOnStatus: Set<number>;
+    constructor(options?: RetryPolicyOptions);
+    /**
+     * Compute the delay before the next retry attempt.
+     *
+     * @param attempt - Current attempt number (1-based)
+     * @param retryAfter - Server-specified retry-after value (if any)
+     * @returns Delay in seconds before next attempt
+     */
+    computeDelay(attempt: number, retryAfter?: number): number;
+    /**
+     * Check if a status code should trigger a retry.
+     */
+    shouldRetry(statusCode: number): boolean;
+}
+
+/**
+ * Telemetry support for tracking API requests.
+ */
+/**
+ * Event emitted for each API request attempt.
+ */
+interface TelemetryEvent {
+    /** HTTP method (GET, POST, etc.) */
+    method: string;
+    /** API path */
+    path: string;
+    /** Transport type (e.g. 'http') */
+    transport: string;
+    /** Attempt number (1-based) */
+    attempt: number;
+    /** HTTP status code (if available) */
+    statusCode?: number;
+    /** Request ID from response headers */
+    requestId?: string;
+    /** Trace ID from response body */
+    traceId?: string;
+    /** Retry-after value (if rate limited) */
+    retryAfter?: string;
+    /** Request duration in milliseconds */
+    elapsedMs?: number;
+    /** Exception (if request failed) */
+    error?: Error;
+    /** Error response body (if status >= 400) */
+    errorBody?: unknown;
+}
+/**
+ * Callback function for telemetry events.
+ */
+type TelemetryHook = (event: TelemetryEvent) => void;
+/**
+ * Safely invoke a telemetry hook, ignoring any exceptions.
+ */
+declare function safeCall(hook: TelemetryHook | undefined, event: TelemetryEvent): void;
+/**
+ * Create a telemetry event.
+ */
+declare function createTelemetryEvent(method: string, path: string, transport: string, attempt: number, options?: Partial<Omit<TelemetryEvent, 'method' | 'path' | 'transport' | 'attempt'>>): TelemetryEvent;
+
+/**
+ * Web IQ SDK for the Web IQ API.
+ */
+
+/**
+ * Options for creating a Web IQ client.
+ */
+interface WebIQClientOptions {
+    /** Your Web IQ API key (use this OR credential/auth) */
+    apiKey?: string;
+    /** An `azure-identity` `TokenCredential`. */
+    credential?: TokenCredential;
+    /** Optional OAuth scope. Defaults to {@link DEFAULT_SCOPE}. */
+    scope?: string;
+    /** Custom AuthProvider instance */
+    auth?: AuthProvider;
+    /** Base URL for the API (default: https://api.microsoft.ai/v3) */
+    baseUrl?: string;
+    /** Optional callback for telemetry events */
+    telemetryHook?: TelemetryHook;
+    /**
+     * Default per-request timeout in milliseconds. Individual calls can
+     * override this with their own `timeout` option.
+     */
+    timeout?: number;
+    /** Retry policy (or options) applied to every request. */
+    retry?: RetryPolicy | RetryPolicyOptions;
+    /**
+     * Custom fetch function for advanced networking (e.g., proxy support, custom TLS).
+     * Must be compatible with the global `fetch` signature.
+     * If not provided, the global `fetch` is used.
+     *
+     * @example
+     * ```typescript
+     * import { ProxyAgent } from "undici";
+     *
+     * const proxyAgent = new ProxyAgent("http://my-proxy:8080");
+     * const client = new WebIQClient({
+     *   apiKey: "key",
+     *   // `dispatcher` is a Node/undici-specific option; the FetchFunction
+     *   // type accepts extra init fields so no type assertion is needed.
+     *   fetchFn: (url, init) => fetch(url, { ...init, dispatcher: proxyAgent }),
+     * });
+     * ```
+     */
+    fetchFn?: FetchFunction;
+}
+/**
+ * Web IQ client for the Web IQ API.
+ *
+ * @example
+ * ```typescript
+ * // Using API key
+ * const client = new WebIQClient({ apiKey: "your-api-key" });
+ *
+ * // Search the web
+ * const results = await client.web.search("Python programming");
+ * for (const result of results.webResults ?? []) {
+ *   console.log(result.title, result.url);
+ * }
+ *
+ * // Close when done
+ * await client.close();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using EntraID via any azure-identity credential
+ * import { DefaultAzureCredential } from "@azure/identity";
+ *
+ * const client = new WebIQClient({
+ *   credential: new DefaultAzureCredential(),
+ * });
+ * ```
+ */
+declare class WebIQClient {
+    /** Web search resource */
+    readonly web: WebResource;
+    /** News search resource */
+    readonly news: NewsResource;
+    /** Videos search resource */
+    readonly videos: VideosResource;
+    /** Images search resource */
+    readonly images: ImagesResource;
+    /** Browse resource */
+    readonly browse: BrowseResource;
+    /** Classic search resource */
+    readonly classic: ClassicResource;
+    private readonly _transport;
+    private readonly _auth;
+    constructor(options: WebIQClientOptions);
+    /**
+     * Close the client and release resources.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create a Web IQ client using the provided options.
+ *
+ * This is an alternative to using `new WebIQClient(options)`.
+ */
+declare function createClient(options: WebIQClientOptions): WebIQClient;
+
+/**
+ * Web IQ SDK error classes.
+ */
+/**
+ * Base exception for all Web IQ SDK errors.
+ */
+declare class WebIQError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Raised when the SDK cannot connect to the API.
+ */
+declare class APIConnectionError extends WebIQError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Raised when the API returns an error status code.
+ */
+declare class APIStatusError extends WebIQError {
+    readonly statusCode: number;
+    readonly body?: unknown;
+    readonly requestId?: string;
+    readonly traceId?: string;
+    constructor(statusCode: number, message: string, options?: {
+        body?: unknown;
+        requestId?: string;
+        traceId?: string;
+    });
+}
+/**
+ * Raised when the API rate limit is exceeded (429 standard rate-limit, or 430
+ * for /browse-specific concurrency limit).
+ */
+declare class RateLimitError extends APIStatusError {
+    constructor(statusCode: number, message: string, options?: {
+        body?: unknown;
+        requestId?: string;
+        traceId?: string;
+    });
+    /** The retry-after value from the API response body, if available. */
+    get retryAfter(): string | undefined;
+}
+/**
+ * Raised when authentication fails (401).
+ */
+declare class AuthenticationError extends APIStatusError {
+    constructor(statusCode: number, message: string, options?: {
+        body?: unknown;
+        requestId?: string;
+        traceId?: string;
+    });
+}
+/**
+ * Raised when the request is rejected with HTTP 403 (e.g. content filtering,
+ * URL excluded, or service not enabled for the API key).
+ *
+ * The credentials are valid; the operation itself is not permitted.
+ * Inspect `error.body.errorCode` to distinguish the exact reason.
+ */
+declare class PermissionDeniedError extends APIStatusError {
+    constructor(statusCode: number, message: string, options?: {
+        body?: unknown;
+        requestId?: string;
+        traceId?: string;
+    });
+}
+
+/**
+ * HTTP transport implementation.
+ */
+
+/**
+ * HTTP transport options.
+ */
+interface HttpTransportOptions {
+    /** Base URL for the API */
+    baseUrl: string;
+    /** Authentication provider */
+    auth: AuthProvider;
+    /** Optional telemetry hook */
+    telemetryHook?: TelemetryHook;
+    /** Optional retry policy */
+    retry?: RetryPolicy;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /**
+     * Custom fetch function for advanced networking (e.g., proxy support, custom TLS).
+     * Must be compatible with the global `fetch` signature.
+     * If not provided, the global `fetch` is used.
+     */
+    fetchFn?: FetchFunction;
+}
+/**
+ * HTTP transport using native fetch.
+ */
+declare class HttpTransport implements Transport {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly telemetry?;
+    private readonly retry;
+    private readonly timeout;
+    private readonly fetchFn;
+    private readonly activeControllers;
+    private closed;
+    constructor(options: HttpTransportOptions);
+    request<T = unknown>(options: TransportRequestOptions): Promise<T>;
+    close(): Promise<void>;
+}
+
+export { APIConnectionError, APIStatusError, ApiKeyAuth, type AuthProvider, AuthenticationError, BrowseContentFormat, type BrowseFetchOptions, type BrowseParams, BrowseResource, type BrowseResponse, ClassicResource, type ClassicSearchOptions, type ClassicSearchParams, ContentFormat, DEFAULT_SCOPE, DEFAULT_TIMEOUT, EntraIDAuth, type FetchFunction, HttpTransport, type HttpTransportOptions, ImageAspectRatio, ImageColor, type ImageItem, type ImageSearchOptions, ImageSize, ImagesResource, type ImagesResponse, type ImagesSearchParams, type NewsItem, NewsResource, type NewsResponse, type NewsSearchOptions, type NewsSearchParams, type NewsThumbnail, PermissionDeniedError, type PlaylistItem, type PlaylistVideo, type QuerySignals, RateLimitError, RetryPolicy, type RetryPolicyOptions, SafeSearch, SafeSearchMode, type SearchClassicResponse, type TelemetryEvent, type TelemetryHook, type TokenCredential, type Transport, type TransportRequestOptions, VideoDuration, type VideoItem, type VideoMoment, VideoResolution, type VideoSearchOptions, VideosResource, type VideosResponse, type VideosSearchParams, WebIQClient, type WebIQClientOptions, WebIQError, WebResource, type WebResponse, type WebResult, type WebSearchOptions, type WebSearchParams, createAuth, createClient, createTelemetryEvent, safeCall };