@microsoft/webiq 0.1.8 → 1.0.0

package/README.md

@@ -2,11 +2,16 @@
 
 Official TypeScript SDK for Web IQ APIs.
 
-[![Node.js 22+](https://img.shields.io/badge/node-22+-green.svg)](https://nodejs.org/)
+[![Node.js ^22.13.0 or >=24](https://img.shields.io/badge/node-%5E22.13.0%20%7C%7C%20%3E%3D24-green.svg)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#license)
 
+For product guides and API documentation, see
+[Microsoft Web IQ documentation](https://learn.microsoft.com/en-us/web-iq/).
+
 ## Installation
 
+Requires Node.js 22.x starting at 22.13.0, or Node.js 24 or later, and npm 10+.
+
 ```bash
 npm install @microsoft/webiq
 ```
@@ -52,9 +57,12 @@ await client.close();
 
 ## Authentication
 
-### API Key
+For Web IQ authentication, see
+[Authenticate with Microsoft Web IQ](https://learn.microsoft.com/en-us/web-iq/get-started/authentication).
+
+The SDK supports API key and Microsoft Entra ID authentication.
 
-Get an API key at [webiq.microsoft.ai](https://webiq.microsoft.ai).
+### API Key
 
 ```typescript
 import { WebIQClient } from '@microsoft/webiq';
@@ -64,9 +72,26 @@ const client = new WebIQClient({
 });
 ```
 
-### EntraID (Azure AD)
+### Microsoft Entra ID
+
+Install the optional Azure credential package:
+
+```bash
+npm install "@azure/identity@>=4.13.1"
+```
+
+Pass a `TokenCredential`, such as `DefaultAzureCredential`:
+
+```typescript
+import { DefaultAzureCredential } from '@azure/identity';
+import { WebIQClient } from '@microsoft/webiq';
+
+const client = new WebIQClient({
+  credential: new DefaultAzureCredential(),
+});
+```
 
-Pass any `@azure/identity` `TokenCredential`:
+### Calling more than one AppID
 
 ```typescript
 import { DefaultAzureCredential } from '@azure/identity';
@@ -74,7 +99,11 @@ import { WebIQClient } from '@microsoft/webiq';
 
 const client = new WebIQClient({
   credential: new DefaultAzureCredential(),
+  appId: 'your-app-id',
 });
+
+await client.web.search('TypeScript programming');
+await client.close();
 ```
 
 ## API Reference
@@ -92,9 +121,6 @@ const results = await client.web.search(query, {
   contentFormat: ContentFormat.HTML, // PASSAGE, TEXT, HTML, MARKDOWN
   maxLength: 10000, // 1-500000
   safeSearch: SafeSearch.STRICT, // OFF, STRICT
-  customSearchConfigId: 'my-config', // Optional custom search config
-  includeDomains: ['example.com'], // Optional allowlist (max 250)
-  excludeDomains: ['spam.example'], // Optional blocklist (max 250)
 });
 // results.webResults → [{title, url, content, lastUpdatedAt, crawledAt, language, isAdult, contentTier}]
 ```
@@ -213,26 +239,21 @@ Every search and browse method accepts an `AbortSignal` via `options.signal`.
 When the signal aborts, the in-flight request is cancelled, retries stop, and
 the signal's `reason` is re-thrown unchanged (no `APIConnectionError` wrapping).
 
-Propagate a client disconnect from an HTTP handler:
+For an HTTP framework that supplies a Fetch API `Request`, propagate its cancellation signal:
 
 ```typescript
-import express from 'express';
-
-app.get('/search', async (req, res) => {
-  try {
-    const result = await client.web.search(req.query.q as string, {
-      signal: req.signal, // express/fastify expose the request's AbortSignal
-    });
-    res.json(result);
-  } catch (err) {
-    if (err instanceof DOMException && err.name === 'AbortError') return; // client gone
-    throw err;
+async function handleSearch(request: Request): Promise<Response> {
+  const query = new URL(request.url).searchParams.get('q');
+  if (!query) {
+    return new Response('Missing search query', { status: 400 });
   }
-});
+  const result = await client.web.search(query, { signal: request.signal });
+  return Response.json(result);
+}
 ```
 
-Apply a wall-clock budget that includes retries (the `timeout` option is per
-attempt only):
+Use a timeout signal shared across retry attempts (the `timeout` option resets
+for each attempt):
 
 ```typescript
 const result = await client.web.search('latest news', {
@@ -240,11 +261,13 @@ const result = await client.web.search('latest news', {
 });
 ```
 
-Combine multiple signals (e.g. a request signal plus a wall-clock cap):
+An active retry delay or credential lookup may finish before cancellation is observed.
+
+Combine multiple signals (e.g. a request signal plus a timeout):
 
 ```typescript
 const result = await client.web.search('latest news', {
-  signal: AbortSignal.any([req.signal, AbortSignal.timeout(5_000)]),
+  signal: AbortSignal.any([request.signal, AbortSignal.timeout(5_000)]),
 });
 ```
 
@@ -254,6 +277,12 @@ For advanced HTTP settings — proxy, custom TLS, mTLS, etc. — pass a custom
 `fetchFn` that wraps the global `fetch`. Spread `init` in your wrapper
 so headers, body, and the internal `AbortSignal` are preserved.
 
+Install the optional proxy package for this example:
+
+```bash
+npm install undici
+```
+
 ```typescript
 import { ProxyAgent } from 'undici';
 import { WebIQClient } from '@microsoft/webiq';
@@ -262,47 +291,124 @@ const proxyAgent = new ProxyAgent('http://my-proxy:8080');
 
 const client = new WebIQClient({
   apiKey: 'your-api-key',
-  // `dispatcher` is a Node/undici-specific init field; the `FetchFunction`
-  // type accepts extra fields so no type assertion is needed.
-  fetchFn: (url, init) => fetch(url, { ...init, dispatcher: proxyAgent }),
+  fetchFn: (url, init) => {
+    // Keep the Node-specific option in a variable so this also type-checks
+    // when the project includes DOM fetch types.
+    const proxyInit = { ...init, dispatcher: proxyAgent };
+    return fetch(url, proxyInit);
+  },
 });
 ```
 
 ### Telemetry
 
+Set `telemetryHook` to observe each HTTP request attempt:
+
 ```typescript
-import { WebIQClient, TelemetryEvent } from '@microsoft/webiq';
+import { WebIQClient } from '@microsoft/webiq';
 
 const client = new WebIQClient({
-  apiKey: 'your-api-key',
-  telemetryHook: (event: TelemetryEvent) => {
-    console.log(`${event.method} ${event.path} → ${event.statusCode} (${event.elapsedMs}ms)`);
+  apiKey: process.env.WEBIQ_API_KEY,
+  telemetryHook: (event) => {
+    console.log(
+      `${event.method} ${event.path}: ` +
+        `status=${event.statusCode}, attempt=${event.attempt}, elapsed=${event.elapsedMs}ms`,
+    );
   },
 });
+
+await client.web.search('TypeScript programming');
+await client.close();
+```
+
+Each `TelemetryEvent` carries `method`, `path`, `transport`, `attempt` (1-based; increments on every retry), `statusCode`, `requestId`, `traceId`, `retryAfter`, `elapsedMs` (per-attempt duration), `responseSizeBytes` (response body size in bytes, set whenever a response is received), `error`, and `errorBody`.
+
+## Click and citation feedback
+
+For instrumentation setup and behavior, see
+[Instrument Microsoft Web IQ usage](https://learn.microsoft.com/en-us/web-iq/guides/instrumentation).
+
+These snippets use an open `client`, the original search `response`, and a
+`result` from that response.
+
+### Click
+
+Call when the user clicks `result`. Use the returned navigation URL in your
+application's router or redirect response.
+
+```typescript
+const click = await client.feedback.pushEvents({
+  response,
+  type: 'click',
+  events: [{ result }],
+  navigation: 'manual',
+  failureMode: 'throw',
+});
+
+const outcome = click.outcomes[0];
+if (outcome?.type === 'click') {
+  console.log('Navigate to:', outcome.navigationUrl);
+}
+```
+
+### Citation
+
+Call when the generated answer actually cites `result`.
+
+```typescript
+if (response.instrumentationCitationBase) {
+  await client.feedback.pushEvents({
+    response,
+    type: 'citation',
+    events: [{ results: [result] }],
+    failureMode: 'throw',
+  });
+}
 ```
 
 ## Error Handling
 
-The SDK throws specific error types for different error conditions. All errors extend `WebIQError`.
+For detailed error definition, see [Microsoft Web IQ error handling](https://learn.microsoft.com/en-us/web-iq/reference/error-handling)
+
+The SDK's API and connection error classes extend `WebIQError`. Invalid client configuration throws a standard `Error`, and caller cancellation propagates the signal's reason unchanged.
 
 ### Error Hierarchy
 
-| Error Class             | HTTP Status                  | When                                              |
-| ----------------------- | ---------------------------- | ------------------------------------------------- |
-| `AuthenticationError`   | 401                          | Invalid or missing API key                        |
-| `PermissionDeniedError` | 403                          | Authenticated but not authorized for the resource |
-| `RateLimitError`        | 429, 430                     | Rate limit / concurrent-request limit exceeded    |
-| `APIStatusError`        | 400, 404, 500, 503, 504, ... | All other HTTP errors                             |
-| `APIConnectionError`    | —                            | Network issues, DNS failures, timeouts            |
-| `WebIQError`            | —                            | Base class for all SDK errors                     |
+| Error Class             | HTTP Status | When                                                |
+| ----------------------- | ----------- | --------------------------------------------------- |
+| `BadRequestError`       | 400         | Invalid request                                     |
+| `AuthenticationError`   | 401         | Invalid or missing API key                          |
+| `PermissionDeniedError` | 403         | Authenticated but not authorized for the resource   |
+| `NotFoundError`         | 404         | Requested resource or Browse document was not found |
+| `RateLimitError`        | 429, 430    | Rate limit / concurrent-request limit exceeded      |
+| `APIStatusError`        | 500, ...    | Other HTTP errors                                   |
+| `APIConnectionError`    | —           | Network issues, DNS failures, timeouts              |
+| `WebIQError`            | —           | Base class for SDK HTTP and connection errors       |
 
-`PermissionDeniedError` and `RateLimitError` both extend `APIStatusError`, so a broader `instanceof APIStatusError` check still matches them.
+`BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, and `RateLimitError` all extend `APIStatusError`, so a broader `instanceof APIStatusError` check still matches them.
+
+### Retries and Browse responses
+
+The default retry statuses are `408`, `500`, `502`, `520`, `523`, and `524`.
+The latter three cover granular Browse system errors. A valid body `retryAfter`
+is honored in full; `maxDelaySeconds` caps only generated exponential backoff.
+Timeouts apply per attempt, not to server-directed waits, which can be long.
+Use `maxRetries: 0` to manage retry deadlines in your application, or provide an
+`AbortSignal` to cancel the call, including retry waits.
+
+HTTP 400 and 404 are not retried by default, but explicit `retryOnStatus`
+selections are honored. `BadRequestError` and `NotFoundError` are thrown after
+the configured retry budget is exhausted.
+
+Browse `202 Accepted` returns a normal response without automatic polling.
+Use its `url` and UTC `retryAfter` timestamp to poll later. Partial HTTP 200
+responses can include `truncationReason`, such as `"encumbrance"`.
 
 ### Rate limits are never auto-retried
 
 The SDK does **not** automatically retry `429` (rate limit) or `430` (concurrent-request limit) responses. As soon as the API returns one, the transport throws `RateLimitError` so your application can decide what to do — back off, queue the request, surface it to the user, etc. Generic retry settings (`RetryPolicy.retryOnStatus`, `maxRetries`) do **not** apply to rate limits.
 
-The server reports the back-off hint in the response **body** as the `retryAfter` field — typically a duration with an `s` suffix (e.g. `"30s"`, `"60s"`). The SDK surfaces that value unchanged on `error.retryAfter`.
+The server reports the back-off hint in the response **body** as the optional `retryAfter` field: a duration with an `s` suffix (e.g. `"30s"`, `"60s"`) or, for granular Browse errors, an ISO8601 UTC timestamp. The SDK surfaces that value unchanged on `error.retryAfter`.
 
 ```typescript
 import { RateLimitError } from '@microsoft/webiq';
@@ -327,6 +433,8 @@ import {
   APIConnectionError,
   APIStatusError,
   AuthenticationError,
+  BadRequestError,
+  NotFoundError,
   PermissionDeniedError,
   RateLimitError,
 } from '@microsoft/webiq';
@@ -334,17 +442,21 @@ import {
 try {
   const results = await client.web.search('test');
 } catch (error) {
-  if (error instanceof PermissionDeniedError) {
+  if (error instanceof BadRequestError) {
+    console.error(`Bad request (HTTP ${error.statusCode}):`, error.message);
+  } else if (error instanceof PermissionDeniedError) {
     // 403 — authenticated, but not allowed to call this resource
     console.error(`Forbidden (HTTP ${error.statusCode}):`, error.message);
   } else if (error instanceof AuthenticationError) {
     // 401 — invalid or missing API key
     console.error(`Auth failed (HTTP ${error.statusCode}):`, error.message);
+  } else if (error instanceof NotFoundError) {
+    console.error(`Not found (HTTP ${error.statusCode}):`, error.message);
   } else if (error instanceof RateLimitError) {
     // 429 or 430 — rate limit / concurrent-request limit (never auto-retried)
     console.error(`Rate limited. Retry after: ${error.retryAfter}`);
   } else if (error instanceof APIStatusError) {
-    // Other HTTP errors (400, 404, 500, 503, 504, etc.)
+    // Other HTTP errors (500, etc.)
     console.error(`API error (HTTP ${error.statusCode}):`, error.message);
   } else if (error instanceof APIConnectionError) {
     // Network issues
@@ -355,30 +467,25 @@ try {
 
 ### Inspecting Error Details
 
-All `APIStatusError` instances (including `PermissionDeniedError` and `RateLimitError`) expose the full error response body. The pattern below applies when the **server** rejects a request (e.g. a 4xx the SDK couldn't pre-validate, or a transient 5xx). `browse.fetch` is a convenient way to trigger one — a missing or filtered URL surfaces as a structured error:
+All `APIStatusError` instances expose `errorCategory`, `errorCode`, `userMessage`, `technicalDetails`, `retryAfter`, `requestId`, and `traceId` directly, without validating an error-response model. Missing optional fields are `undefined`; the original response remains available in `body`. The following example uses an invalid API key to demonstrate a 401 authentication error.
 
 ```typescript
-import { WebIQClient, APIStatusError } from '@microsoft/webiq';
+import { WebIQClient, AuthenticationError } from '@microsoft/webiq';
 
 async function main() {
-  const client = new WebIQClient({ apiKey: 'your-api-key' });
+  const client = new WebIQClient({ apiKey: 'invalid-api-key' });
 
   try {
-    await client.browse.fetch('https://www.not-microsoft.com');
+    await client.web.search('Microsoft Web IQ');
   } catch (error) {
-    if (error instanceof APIStatusError) {
-      console.error(`Status: ${error.statusCode}`); // e.g. 404
-      console.error(`Message: ${error.message}`); // e.g. "No result is found"
-
-      // Full error body from the API response
-      if (error.body && typeof error.body === 'object') {
-        const body = error.body as Record<string, unknown>;
-        console.error(`Error code: ${body.errorCode}`); // e.g. "BrowseApiDocNotFound"
-        console.error(`Category: ${body.errorCategory}`); // e.g. "UserError"
-        console.error(`Details: ${body.technicalDetails}`); // e.g. "NotFound"
-        console.error(`Trace ID: ${body.traceId}`); // for debugging with support
-        console.error(`Retry after: ${body.retryAfter}`); // for retryable errors
-      }
+    if (error instanceof AuthenticationError) {
+      console.error(error.statusCode); // 401
+      console.error(error.errorCategory);
+      console.error(error.errorCode);
+      console.error(error.userMessage);
+      console.error(error.traceId);
+    } else {
+      throw error;
     }
   }
 }
@@ -399,3 +506,14 @@ const [web, news, videos] = await Promise.all([
 ## License
 
 MIT
+
+## Release History
+
+### 1.0.0
+
+#### Features Added
+
+- Web, news, video, and image search, plus page browsing.
+- API key and Microsoft Entra ID authentication.
+- Click and citation feedback.
+- Error handling and telemetry support