@microsoft/webiq 0.1.7 → 1.0.0

package/dist/index.d.ts

@@ -89,21 +89,45 @@ declare enum SafeSearch {
     STRICT = "strict"
 }
 
+declare enum RiskLevel {
+    LOW = "low",
+    MODERATE = "moderate",
+    HIGH = "high",
+    VERY_HIGH = "veryHigh"
+}
+
+type WebQuerySignals = {
+    /**
+     * Indicates whether fresh documents should be prioritized over other documents for this query.
+     */
+    freshness?: boolean | null;
+};
+
 declare enum ContentTier {
     STANDARD = "standard",
     ENTITLED = "entitled",
     PREMIUM = "premium"
 }
 
+declare enum SourceQuality {
+    INSUFFICIENT = "insufficient",
+    ADEQUATE = "adequate",
+    PREFERRED = "preferred"
+}
+
 type WebResult = {
     /**
      * The title of the webpage.
      */
     title?: string | null;
     /**
-     * The source URL of the webpage.
+     * The source URL of the webpage. For China users with URL redirection enabled, this field instead contains the same redirect URL as clickUrl.
      */
     url?: string | null;
+    /**
+     * The destination host for the result. Returned only for China users with URL redirection enabled.
+     */
+    domain?: string | null;
     /**
      * The detailed content of the webpage.
      */
@@ -125,6 +149,7 @@ type WebResult = {
      */
     isAdult?: boolean;
     contentTier?: ContentTier;
+    sourceQuality?: SourceQuality;
     /**
      * Redirect URL that proxies through Bing. Only present when redirect is enabled.
      */
@@ -140,6 +165,7 @@ type WebResponse = {
      * List of web page results.
      */
     webResults?: Array<WebResult> | null;
+    querySignals?: WebQuerySignals;
     /**
      * Base URL for click ping requests. Append an instrumentationSuffix value from a result item to form the full ping URL.
      */
@@ -152,6 +178,7 @@ type WebResponse = {
      * Trace ID for debugging and tracking.
      */
     traceId?: string | null;
+    riskLevel?: RiskLevel;
 };
 
 /**
@@ -228,9 +255,13 @@ type NewsItem = {
      */
     title?: string | null;
     /**
-     * The source URL of the news.
+     * The source URL of the news article. For China users with URL redirection enabled, this field instead contains the same redirect URL as clickUrl.
      */
     url?: string | null;
+    /**
+     * The destination host for the result. Returned only for China users with URL redirection enabled.
+     */
+    domain?: string | null;
     /**
      * The detailed content of the news.
      */
@@ -244,6 +275,10 @@ type NewsItem = {
      * The last crawled date of the news, follows ISO8601 format.
      */
     crawledAt?: string | null;
+    /**
+     * The language of the news article, uses ISO 639-1 language code.
+     */
+    language?: string | null;
     /**
      * Publisher name, such as 'USA TODAY | MSN', 'CNN', etc.
      */
@@ -398,9 +433,13 @@ type VideoItem = {
      */
     title?: string | null;
     /**
-     * The video source URL.
+     * The source URL of the video. For China users with URL redirection enabled, this field instead contains the same redirect URL as clickUrl.
      */
     url?: string | null;
+    /**
+     * The destination host for the result. Returned only for China users with URL redirection enabled.
+     */
+    domain?: string | null;
     /**
      * Description of the video content. This is either given by video uploader or generated by LLM
      */
@@ -569,9 +608,13 @@ type ImageItem = {
      */
     title?: string | null;
     /**
-     * The source URL of the image.
+     * The source URL of the image. For China users with URL redirection enabled, this field instead contains the same redirect URL as clickUrl.
      */
     url?: string | null;
+    /**
+     * The destination host for the result. Returned only for China users with URL redirection enabled.
+     */
+    domain?: string | null;
     /**
      * The host page URL of the image.
      */
@@ -700,7 +743,7 @@ declare enum LiveCrawlMode {
 
 type BrowseResponse = {
     /**
-     * The URL of the web page.
+     * The URL of the web page, or the URL to retry when a crawl is pending.
      */
     url?: string | null;
     /**
@@ -724,13 +767,21 @@ type BrowseResponse = {
      */
     crawledAt?: string | null;
     /**
-     * Retry after value when on-demand crawl is in progress. Only present when the page needs to be crawled.
+     * Upstream ISO8601 UTC timestamp indicating when to retry a pending crawl. Only present on accepted (202) responses when supplied by the service.
      */
     retryAfter?: string | null;
     /**
      * Trace ID for debugging and tracking.
      */
     traceId?: string | null;
+    /**
+     * Only present as false when an auto or force live-crawl response returns a stale page. Omitted otherwise.
+     */
+    liveCrawlSucceeded?: boolean | null;
+    /**
+     * Reason partial content was returned, such as encumbrance. Omitted when not supplied by the service; partial content remains a successful (200) response.
+     */
+    truncationReason?: string | null;
 };
 
 /**
@@ -790,10 +841,11 @@ interface RetryPolicyOptions {
     maxRetries?: number;
     /** Base delay in seconds for exponential backoff (default: 0.25) */
     baseDelaySeconds?: number;
-    /** Maximum delay in seconds (default: 4.0) */
+    /** Maximum generated backoff in seconds (default: 4.0); server hints are not capped. */
     maxDelaySeconds?: number;
     /**
-     * HTTP status codes that trigger a retry. 429 and 430 (rate-limit /
+     * HTTP status codes that trigger a retry. Explicit 400/404 selections are
+     * honored, although excluded by default. 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.
@@ -848,6 +900,8 @@ interface TelemetryEvent {
     retryAfter?: string;
     /** Request duration in milliseconds */
     elapsedMs?: number;
+    /** Size of the response body in bytes (if a response was received) */
+    responseSizeBytes?: number;
     /** Exception (if request failed) */
     error?: Error;
     /** Error response body (if status >= 400) */
@@ -866,6 +920,138 @@ declare function safeCall(hook: TelemetryHook | undefined, event: TelemetryEvent
  */
 declare function createTelemetryEvent(method: string, path: string, transport: string, attempt: number, options?: Partial<Omit<TelemetryEvent, 'method' | 'path' | 'transport' | 'attempt'>>): TelemetryEvent;
 
+interface FeedbackResponse {
+    instrumentationClickBase?: string | null;
+    instrumentationCitationBase?: string | null;
+}
+interface FeedbackResult {
+    url?: string | null;
+    clickUrl?: string | null;
+    instrumentationSuffix?: string | null;
+}
+type ClickKind = 'redirect' | 'ping' | 'untracked';
+interface PreparedClick {
+    kind: ClickKind;
+    navigationUrl: string;
+    pingUrl: string | null;
+}
+type FeedbackErrorCode = 'missing_navigation_url' | 'missing_citation_base' | 'empty_citation_results' | 'missing_instrumentation_suffix' | 'malformed_instrumentation_suffix' | 'invalid_feedback_input' | 'feedback_connection' | 'feedback_timeout' | 'feedback_cancelled' | 'feedback_http' | 'feedback_navigation';
+declare class FeedbackError extends Error {
+    readonly code: FeedbackErrorCode;
+    readonly statusCode?: number | undefined;
+    constructor(code: FeedbackErrorCode, message: string, statusCode?: number | undefined);
+}
+declare class InvalidFeedbackInputError extends FeedbackError {
+    constructor(message?: string, code?: FeedbackErrorCode);
+}
+declare class MissingInstrumentationError extends FeedbackError {
+    constructor();
+}
+declare class InvalidInstrumentationSuffixError extends FeedbackError {
+    constructor(code?: FeedbackErrorCode);
+}
+declare class FeedbackConnectionError extends FeedbackError {
+    constructor();
+}
+declare class FeedbackTimeoutError extends FeedbackError {
+    constructor();
+}
+declare class FeedbackCancelledError extends FeedbackError {
+    constructor();
+}
+declare class FeedbackHttpError extends FeedbackError {
+    constructor(statusCode: number);
+}
+declare class FeedbackNavigationError extends FeedbackError {
+    constructor();
+}
+declare function buildClickPingUrl(response: FeedbackResponse, result: FeedbackResult): string | null;
+declare function prepareClick(response: FeedbackResponse, result: FeedbackResult): PreparedClick;
+declare function buildCitationPingUrl(response: FeedbackResponse, results: readonly FeedbackResult[]): string;
+
+type InstrumentationContext = FeedbackResponse;
+type InstrumentedResult = FeedbackResult;
+interface FeedbackHttpResponse {
+    status: number;
+}
+interface FeedbackSender {
+    send(url: string, options?: {
+        signal?: AbortSignal;
+        timeout?: number;
+    }): Promise<FeedbackHttpResponse>;
+}
+interface NavigationHandler {
+    navigate(url: string): void | Promise<void>;
+}
+interface FeedbackClientOptions {
+    sender?: FeedbackSender;
+    navigationHandler?: NavigationHandler;
+}
+interface CitationFeedbackEvent {
+    results: readonly InstrumentedResult[];
+}
+interface ClickFeedbackEvent {
+    result: InstrumentedResult;
+}
+interface CommonPushEventsOptions {
+    response: InstrumentationContext;
+    navigation?: 'auto' | 'manual';
+    navigationPolicy?: 'always' | 'on-feedback-success';
+    failureMode?: 'collect' | 'throw';
+    signal?: AbortSignal;
+    /**
+     * Feedback timeout in milliseconds, greater than 0 and at most 2_147_483_647.
+     * Independent of Search configuration.
+     */
+    timeout?: number;
+}
+interface CitationPushEventsOptions extends CommonPushEventsOptions {
+    type: 'citation';
+    events: readonly [CitationFeedbackEvent, ...CitationFeedbackEvent[]];
+}
+interface ClickPushEventsOptions extends CommonPushEventsOptions {
+    type: 'click';
+    events: readonly [ClickFeedbackEvent];
+}
+type PushEventsOptions = CitationPushEventsOptions | ClickPushEventsOptions;
+type ClickFeedbackStatus = 'submitted' | 'dispatched' | 'pending-navigation' | 'not-instrumented' | 'failed';
+type ClickNavigationStatus = 'navigated' | 'required' | 'blocked' | 'failed';
+type FeedbackOutcome = {
+    type: 'citation';
+    feedbackStatus: 'submitted' | 'failed';
+    navigationStatus: 'not-applicable';
+    resultCount: number;
+    feedbackError?: FeedbackError;
+} | {
+    type: 'click';
+    clickMode: ClickKind;
+    feedbackStatus: ClickFeedbackStatus;
+    navigationStatus: ClickNavigationStatus;
+    navigationUrl: string;
+    feedbackError?: FeedbackError;
+    navigationError?: FeedbackError;
+};
+interface PushEventsResult {
+    outcomes: readonly FeedbackOutcome[];
+    submittedEventCount: number;
+    dispatchedEventCount: number;
+    requestCount: number;
+    navigated: boolean;
+}
+/** Uses only global fetch, never the authenticated Search transport or its custom fetch. */
+declare class DefaultFeedbackSender implements FeedbackSender {
+    send(url: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<FeedbackHttpResponse>;
+}
+declare class FeedbackClient {
+    private readonly sender;
+    private readonly navigator?;
+    constructor(options?: FeedbackClientOptions);
+    pushEvents(options: PushEventsOptions): Promise<PushEventsResult>;
+    private send;
+}
+
 /**
  * Web IQ SDK for the Web IQ API.
  */
@@ -874,6 +1060,8 @@ declare function createTelemetryEvent(method: string, path: string, transport: s
  * Options for creating a Web IQ client.
  */
 interface WebIQClientOptions {
+    /** Isolated feedback sender and optional application navigation handler. */
+    feedback?: FeedbackClientOptions;
     /** Your Web IQ API key (use this OR credential/auth) */
     apiKey?: string;
     /** An `azure-identity` `TokenCredential`. */
@@ -884,6 +1072,8 @@ interface WebIQClientOptions {
     auth?: AuthProvider;
     /** Base URL for the API (default: https://api.microsoft.ai/v3) */
     baseUrl?: string;
+    /** Target application for identities mapped to multiple apps; unset/empty omits `appid`. */
+    appId?: string | null;
     /** Optional callback for telemetry events */
     telemetryHook?: TelemetryHook;
     /**
@@ -942,6 +1132,7 @@ interface WebIQClientOptions {
  * ```
  */
 declare class WebIQClient {
+    readonly feedback: FeedbackClient;
     /** Web search resource */
     readonly web: WebResource;
     /** News search resource */
@@ -995,10 +1186,15 @@ declare class APIStatusError extends WebIQError {
         requestId?: string;
         traceId?: string;
     });
+    private stringField;
+    get errorCode(): string | undefined;
+    get errorCategory(): string | undefined;
+    get userMessage(): string | undefined;
+    get technicalDetails(): string | undefined;
+    get retryAfter(): string | undefined;
 }
 /**
- * Raised when the API rate limit is exceeded (429 standard rate-limit, or 430
- * for /browse-specific concurrency limit).
+ * Raised when the API rate limit (429) or Browse crawl limit (430) is exceeded.
  */
 declare class RateLimitError extends APIStatusError {
     constructor(statusCode: number, message: string, options?: {
@@ -1009,6 +1205,22 @@ declare class RateLimitError extends APIStatusError {
     /** The retry-after value from the API response body, if available. */
     get retryAfter(): string | undefined;
 }
+/** Raised when the API rejects an invalid request (400). */
+declare class BadRequestError extends APIStatusError {
+    constructor(statusCode: number, message: string, options?: {
+        body?: unknown;
+        requestId?: string;
+        traceId?: string;
+    });
+}
+/** Raised when the requested resource or Browse document is not found (404). */
+declare class NotFoundError extends APIStatusError {
+    constructor(statusCode: number, message: string, options?: {
+        body?: unknown;
+        requestId?: string;
+        traceId?: string;
+    });
+}
 /**
  * Raised when authentication fails (401).
  */
@@ -1020,11 +1232,11 @@ declare class AuthenticationError extends APIStatusError {
     });
 }
 /**
- * Raised when the request is rejected with HTTP 403 (e.g. content filtering,
- * URL excluded, or service not enabled for the API key).
+ * Raised when an authenticated caller cannot access an endpoint, feature, or
+ * content (403).
  *
  * The credentials are valid; the operation itself is not permitted.
- * Inspect `error.body.errorCode` to distinguish the exact reason.
+ * Inspect `error.errorCode` to distinguish the exact reason.
  */
 declare class PermissionDeniedError extends APIStatusError {
     constructor(statusCode: number, message: string, options?: {
@@ -1221,6 +1433,8 @@ type WebRequest = {
 interface HttpTransportOptions {
     /** Base URL for the API */
     baseUrl: string;
+    /** Optional target application; unset/empty omits the query parameter. */
+    appId?: string | null;
     /** Authentication provider */
     auth: AuthProvider;
     /** Optional telemetry hook */
@@ -1241,16 +1455,18 @@ interface HttpTransportOptions {
  */
 declare class HttpTransport implements Transport {
     private readonly baseUrl;
+    private readonly appId?;
     private readonly auth;
     private readonly telemetry?;
     private readonly retry;
     private readonly timeout;
     private readonly fetchFn;
     private readonly activeControllers;
+    private readonly closeController;
     private closed;
     constructor(options: HttpTransportOptions);
     request<T = unknown>(options: TransportRequestOptions): Promise<T>;
     close(): Promise<void>;
 }
 
-export { APIConnectionError, APIStatusError, type ApiErrorResponse, ApiKeyAuth, type AuthProvider, AuthenticationError, BrowseContentFormat, type BrowseFetchOptions, type BrowseParams, type BrowseRequest, BrowseResource, type BrowseResponse, ContentFormat, ContentTier, DEFAULT_SCOPE, DEFAULT_TIMEOUT, EntraIDAuth, type FetchFunction, HttpTransport, type HttpTransportOptions, ImageAspectRatio, ImageColor, type ImageItem, type ImageSearchOptions, ImageSize, type ImagesRequest, ImagesResource, type ImagesResponse, type ImagesSearchParams, LiveCrawlMode, type NewsItem, type NewsRequest, NewsResource, type NewsResponse, type NewsSearchOptions, type NewsSearchParams, type NewsThumbnail, PermissionDeniedError, type PlaylistItem, type PlaylistVideo, RateLimitError, RetryPolicy, type RetryPolicyOptions, SafeSearch, type TelemetryEvent, type TelemetryHook, type TokenCredential, type Transport, type TransportRequestOptions, VideoDuration, type VideoItem, type VideoMoment, VideoResolution, type VideoSearchOptions, type VideosRequest, VideosResource, type VideosResponse, type VideosSearchParams, WebIQClient, type WebIQClientOptions, WebIQError, type WebRequest, WebResource, type WebResponse, type WebResult, type WebSearchOptions, type WebSearchParams, createAuth, createClient, createTelemetryEvent, safeCall };
+export { APIConnectionError, APIStatusError, type ApiErrorResponse, ApiKeyAuth, type AuthProvider, AuthenticationError, BadRequestError, BrowseContentFormat, type BrowseFetchOptions, type BrowseParams, type BrowseRequest, BrowseResource, type BrowseResponse, type CitationFeedbackEvent, type CitationPushEventsOptions, type ClickFeedbackEvent, type ClickFeedbackStatus, type ClickKind, type ClickNavigationStatus, type ClickPushEventsOptions, type CommonPushEventsOptions, ContentFormat, ContentTier, DEFAULT_SCOPE, DEFAULT_TIMEOUT, DefaultFeedbackSender, EntraIDAuth, FeedbackCancelledError, FeedbackClient, type FeedbackClientOptions, FeedbackConnectionError, FeedbackError, type FeedbackErrorCode, FeedbackHttpError, type FeedbackHttpResponse, FeedbackNavigationError, type FeedbackOutcome, type FeedbackResponse, type FeedbackResult, type FeedbackSender, FeedbackTimeoutError, type FetchFunction, HttpTransport, type HttpTransportOptions, ImageAspectRatio, ImageColor, type ImageItem, type ImageSearchOptions, ImageSize, type ImagesRequest, ImagesResource, type ImagesResponse, type ImagesSearchParams, type InstrumentationContext, type InstrumentedResult, InvalidFeedbackInputError, InvalidInstrumentationSuffixError, LiveCrawlMode, MissingInstrumentationError, type NavigationHandler, type NewsItem, type NewsRequest, NewsResource, type NewsResponse, type NewsSearchOptions, type NewsSearchParams, type NewsThumbnail, NotFoundError, PermissionDeniedError, type PlaylistItem, type PlaylistVideo, type PreparedClick, type PushEventsOptions, type PushEventsResult, RateLimitError, RetryPolicy, type RetryPolicyOptions, RiskLevel, SafeSearch, SourceQuality, type TelemetryEvent, type TelemetryHook, type TokenCredential, type Transport, type TransportRequestOptions, VideoDuration, type VideoItem, type VideoMoment, VideoResolution, type VideoSearchOptions, type VideosRequest, VideosResource, type VideosResponse, type VideosSearchParams, WebIQClient, type WebIQClientOptions, WebIQError, type WebQuerySignals, type WebRequest, WebResource, type WebResponse, type WebResult, type WebSearchOptions, type WebSearchParams, buildCitationPingUrl, buildClickPingUrl, createAuth, createClient, createTelemetryEvent, prepareClick, safeCall };