@microsoft/agents-hosting 1.9.1 → 1.10.0-beta.14.ge6d1defc27

package/src/auth/settings.ts

@@ -24,16 +24,28 @@ const AUTHORITY_DEFAULT = 'https://login.microsoftonline.com'
  * (matched by audience and/or serviceUrl) to a named connection.
  */
 export interface ConnectionMapItem {
+  /** Service URL pattern matched by this route. */
   serviceUrl: string
+  /** Optional token audience matched by this route. */
   audience?: string
+  /** Name of the connection selected by this route. */
   connection: string
 }
 
+/** Default route that selects the standard service connection. */
 export const DEFAULT_CONNECTION_MAP: ConnectionMapItem = { serviceUrl: '*', connection: DEFAULT_CONNECTION }
 
+/** Property names accepted as connection-level settings. */
 export type ConnectionKeys = keyof Omit<AuthConfiguration, 'connections' | 'connectionsMap'>
+/** Property names accepted in a connection-map entry. */
 export type ConnectionMapKeys = keyof ConnectionMapItem
 
+/**
+ * Applies authority, issuer, alias, and connection-map defaults to a configuration.
+ *
+ * @param config - Authentication configuration to normalize.
+ * @returns A normalized copy of the configuration.
+ */
 export function applyDefaultSettings (config: AuthConfiguration) {
   const settings = { ...config }
   settings.authorityEndpoint ??= settings.authority ?? AUTHORITY_DEFAULT
@@ -106,6 +118,13 @@ function trimTrailingSlashes (value: string): string {
   return end === value.length ? value : value.slice(0, end)
 }
 
+/**
+ * Builds the default trusted issuer list for a tenant and authority.
+ *
+ * @param tenantId - Microsoft Entra tenant ID.
+ * @param authority - Authority URL used to determine the cloud and effective tenant.
+ * @returns Trusted Bot Framework and Microsoft Entra issuer URLs.
+ */
 export function getDefaultIssuers (tenantId: string, authority: string) : string[] {
   // Convert empty string to undefined so resolveAuthority applies its 'botframework.com' default
   const t = getEffectiveTenant(tenantId || undefined, authority)
@@ -268,14 +287,23 @@ export interface AuthConfiguration extends ConnectionSettings {
  * Supported authentication types for agent connections.
  */
 export enum AuthType {
+  /** Client authentication using an X.509 certificate. */
   Certificate = 'Certificate',
+  /** Client authentication using a certificate subject name. */
   CertificateSubjectName = 'CertificateSubjectName',
+  /** Client authentication using a client secret. */
   ClientSecret = 'ClientSecret',
+  /** Authentication using a user-assigned managed identity. */
   UserManagedIdentity = 'UserManagedIdentity',
+  /** Authentication using a system-assigned managed identity. */
   SystemManagedIdentity = 'SystemManagedIdentity',
+  /** Authentication using federated identity credentials. */
   FederatedCredentials = 'FederatedCredentials',
+  /** Authentication using a workload identity token. */
   WorkloadIdentity = 'WorkloadIdentity',
+  /** Authentication through Identity Proxy Manager. */
   IdentityProxyManager = 'IdentityProxyManager',
+  /** Authentication through the Microsoft Entra authentication sidecar. */
   EntraAuthSideCar = 'EntraAuthSideCar'
 }
 

package/src/auth/sidecar/sidecarAuthProvider.ts

@@ -134,6 +134,10 @@ export class SidecarAuthProvider implements AuthProvider {
    * On-behalf-of token exchange — not supported by the sidecar provider in Phase 1.
    */
   async acquireTokenOnBehalfOf (scopes: string[], oboAssertion: string): Promise<string>
+
+  /**
+   * On-behalf-of token exchange with explicit authentication settings — not supported by the sidecar provider in Phase 1.
+   */
   async acquireTokenOnBehalfOf (authConfig: AuthConfiguration, scopes: string[], oboAssertion: string): Promise<string>
   async acquireTokenOnBehalfOf (
     _authConfigOrScopes: AuthConfiguration | string[],

package/src/auth/sidecar/sidecarHttpClient.ts

@@ -3,10 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { isIP } from 'node:net'
 import { debug } from '@microsoft/agents-telemetry'
 import { ExceptionHelper } from '@microsoft/agents-activity'
 import { Errors } from '../../errorHelper'
+import { isPrivateOrLoopbackAddress } from '../../utils/ipAddress'
 import {
   DEFAULT_REQUEST_TIMEOUT_MS,
   DEFAULT_RETRY_COUNT,
@@ -23,7 +23,7 @@ const DEFAULT_RETRY_BACKOFF_BASE_MS = 2000
 /**
  * Reusable HTTP client for communicating with the Microsoft Entra Agent ID sidecar (agent container).
  * Handles URL construction, query parameter building, response parsing, retry, and SSRF-safe base
- * URL validation. Uses the native `fetch` API (Node.js 20+).
+ * URL validation.
  */
 export class SidecarHttpClient {
   /** Default per-attempt request timeout (milliseconds). */
@@ -139,68 +139,8 @@ export class SidecarHttpClient {
   }
 
   private static isLoopbackOrPrivateHost (host: string): boolean {
-    // URL.hostname wraps IPv6 literals in brackets (e.g. "[::1]"); strip them before classification.
-    const normalized = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host
-    const ipVersion = isIP(normalized)
-    if (ipVersion === 0) {
-      // DNS host: only "localhost" (and subdomains) is treated as safe.
-      const lower = normalized.toLowerCase()
-      return lower === 'localhost' || lower.endsWith('.localhost')
-    }
-    if (ipVersion === 4) {
-      return SidecarHttpClient.isPrivateOrLoopbackIPv4(normalized)
-    }
-    return SidecarHttpClient.isPrivateOrLoopbackIPv6(normalized)
-  }
-
-  private static isPrivateOrLoopbackIPv4 (host: string): boolean {
-    const b = host.split('.').map((p) => parseInt(p, 10))
-    if (b.length !== 4 || b.some((n) => Number.isNaN(n) || n < 0 || n > 255)) {
-      return false
-    }
-    if (b[0] === 127) return true // 127.0.0.0/8 loopback
-    if (b[0] === 10) return true // 10.0.0.0/8
-    if (b[0] === 172 && b[1] >= 16 && b[1] <= 31) return true // 172.16.0.0/12
-    if (b[0] === 192 && b[1] === 168) return true // 192.168.0.0/16
-    if (b[0] === 169 && b[1] === 254) return true // 169.254.0.0/16 link-local
-    return false
-  }
-
-  private static isPrivateOrLoopbackIPv6 (host: string): boolean {
     const lower = host.toLowerCase()
-    if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') return true // loopback (`::` is the unspecified address, not loopback)
-    // IPv4-mapped/-translated addresses in either dotted (::ffff:127.0.0.1)
-    // or hex-compressed (::ffff:7f00:1) form.
-    const mappedIPv4 = SidecarHttpClient.extractMappedIPv4(lower)
-    if (mappedIPv4) {
-      return SidecarHttpClient.isPrivateOrLoopbackIPv4(mappedIPv4)
-    }
-    const firstHextet = parseInt(lower.split(':')[0], 16)
-    if (!Number.isNaN(firstHextet)) {
-      if ((firstHextet & 0xfe00) === 0xfc00) return true // fc00::/7 unique local
-      if ((firstHextet & 0xffc0) === 0xfe80) return true // fe80::/10 link-local
-      if ((firstHextet & 0xffc0) === 0xfec0) return true // fec0::/10 site-local (deprecated)
-    }
-    return false
-  }
-
-  /**
-   * Extracts the embedded IPv4 address from an IPv4-mapped/-translated IPv6 literal, returning it
-   * in dotted-quad form, or `undefined` if `host` is not such an address. Handles both the dotted
-   * form (`::ffff:127.0.0.1`) and the hex-compressed form Node emits (`::ffff:7f00:1`).
-   */
-  private static extractMappedIPv4 (host: string): string | undefined {
-    const dotted = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/)
-    if (dotted) {
-      return dotted[1]
-    }
-    const hex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
-    if (hex) {
-      const high = parseInt(hex[1], 16)
-      const low = parseInt(hex[2], 16)
-      return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`
-    }
-    return undefined
+    return lower === 'localhost' || lower.endsWith('.localhost') || isPrivateOrLoopbackAddress(host)
   }
 
   /**

package/src/baseAdapter.ts

@@ -88,6 +88,12 @@ export abstract class BaseAdapter {
 
   /**
    * Continues a conversation.
+   *
+   * @remarks
+   * Errors thrown by `logic` are passed to {@link onTurnError}. If the error handler completes
+   * normally, this method resolves. To observe the original error in the caller, catch it inside
+   * `logic` and throw it after this method completes.
+   *
    * @param reference - The conversation reference to continue.
    * @param logic - The logic to execute.
    * @returns A promise representing the completion of the continue operation.

package/src/cards/taskModuleAction.ts

@@ -9,6 +9,12 @@ import { CardAction } from '@microsoft/agents-activity'
  * Represents a task module action.
  */
 export class TaskModuleAction implements CardAction {
+  /**
+   * Creates an action that invokes a `task/fetch` task module.
+   *
+   * @param title The action title.
+   * @param value The action data as an object or JSON string.
+   */
   constructor (title: string, value: any) {
     this.type = 'invoke'
     this.title = title

package/src/cloudAdapter.ts

@@ -152,7 +152,9 @@ function sanitizeForLog (value: string, max = 256): string {
 function truncateActivityForLog (activity: unknown, max = 1024): string {
   try {
     const json = JSON.stringify(activity)
-    if (!json) return '<unserializable>'
+    if (!json) {
+      return '<unserializable>'
+    }
     // Strip C0/DEL/C1 controls + U+2028/U+2029 from the serialized form so
     // attacker-controlled fields (e.g. activity.text) can't forge log lines.
     // eslint-disable-next-line no-control-regex
@@ -651,18 +653,30 @@ export class CloudAdapter extends BaseAdapter {
    * should be rejected with a 400.
    */
   private validateServiceUrl (identity: JwtPayload | undefined, activity: Activity): boolean {
-    if (!this.isOutboundServiceUrlAllowed(activity.serviceUrl)) return false
+    if (!this.isOutboundServiceUrlAllowed(activity.serviceUrl)) {
+      return false
+    }
 
-    if (!identity) return true
-    if (!activity.serviceUrl) return true
+    if (!identity) {
+      return true
+    }
+    if (!activity.serviceUrl) {
+      return true
+    }
 
     const claimValue = identity.serviceurl
-    if (typeof claimValue !== 'string') return true
+    if (typeof claimValue !== 'string') {
+      return true
+    }
 
     let claimHost: string | undefined
     let activityHost: string | undefined
-    try { claimHost = new URL(claimValue).hostname.toLowerCase() } catch { /* invalid */ }
-    try { activityHost = new URL(activity.serviceUrl).hostname.toLowerCase() } catch { /* invalid */ }
+    try {
+      claimHost = new URL(claimValue).hostname.toLowerCase()
+    } catch { /* invalid */ }
+    try {
+      activityHost = new URL(activity.serviceUrl).hostname.toLowerCase()
+    } catch { /* invalid */ }
 
     if (claimHost && activityHost && claimHost === activityHost) {
       return true
@@ -682,7 +696,9 @@ export class CloudAdapter extends BaseAdapter {
    * Applies the shared outbound host policy.
    */
   private isOutboundServiceUrlAllowed (serviceUrl: string | undefined): boolean {
-    if (!this._hostValidator.enabled || !serviceUrl || this._hostValidator.isAllowed(serviceUrl)) return true
+    if (!this._hostValidator.enabled || !serviceUrl || this._hostValidator.isAllowed(serviceUrl)) {
+      return true
+    }
 
     logger.warn(`ServiceUrl host is not in the configured allowed hosts. ServiceUrl='${sanitizeForLog(serviceUrl)}'`)
     return false
@@ -751,6 +767,35 @@ export class CloudAdapter extends BaseAdapter {
 
   /**
    * Continues a conversation.
+   *
+   * @remarks
+   * Errors thrown by `logic` are passed to {@link BaseAdapter.onTurnError}. If the error handler
+   * completes normally, this method resolves. A `try`/`catch` around `continueConversation` will
+   * therefore not observe the original error.
+   *
+   * To observe an error from a proactive operation, catch it inside `logic` and throw it after
+   * `continueConversation` completes:
+   *
+   * ```typescript
+   * let operationFailed = false
+   * let operationError: unknown
+   *
+   * await adapter.continueConversation(botAppId, reference, async (context) => {
+   *   try {
+   *     await context.sendActivity('Proactive message')
+   *   } catch (error) {
+   *     operationFailed = true
+   *     operationError = error
+   *   }
+   * })
+   *
+   * if (operationFailed) {
+   *   throw operationError
+   * }
+   * ```
+   *
+   * Catching the error inside `logic` prevents `onTurnError` from receiving that error.
+   *
    * @param botAppIdOrIdentity - The bot identity to use when continuing the conversation. This can be either:
    * a string containing the bot's App ID (botId) or a JwtPayload object containing identity claims (must include aud).
    * @param reference - The conversation reference to continue.
@@ -891,8 +936,12 @@ export class CloudAdapter extends BaseAdapter {
     if (typeof serviceUrl !== 'string' || !serviceUrl) {
       throw ExceptionHelper.generateException(TypeError, Errors.ServiceUrlRequired)
     }
-    if (!conversationParameters) throw ExceptionHelper.generateException(TypeError, Errors.ConversationParametersRequired)
-    if (!logic) throw ExceptionHelper.generateException(TypeError, Errors.LogicParameterRequired)
+    if (!conversationParameters) {
+      throw ExceptionHelper.generateException(TypeError, Errors.ConversationParametersRequired)
+    }
+    if (!logic) {
+      throw ExceptionHelper.generateException(TypeError, Errors.LogicParameterRequired)
+    }
 
     const identity = CloudAdapter.createIdentity(audience)
     const restClient = await this.createConnectorClient(serviceUrl, audience, identity)

package/src/configuration/configuration.ts

@@ -27,6 +27,7 @@ export type CloudAdapterConfigurationPatch = Partial<{
 export type OutboundHostValidatorConfigurationPatch = Partial<{
   enabled: boolean
   includeDefaultMicrosoftHosts: boolean
+  allowPrivateNetworkAddresses: boolean
   hosts: readonly string[]
 }>
 export type AuthorizationHandlerPatch = Record<string, unknown>
@@ -105,6 +106,7 @@ const connectionMapParsers = {
 const outboundHostValidatorParsers = {
   enabled: asBoolean,
   includeDefaultMicrosoftHosts: asBoolean,
+  allowPrivateNetworkAddresses: asBoolean,
   hosts: asList
 } satisfies Record<string, (value: string) => unknown>
 
@@ -489,7 +491,7 @@ function parseValue (
     ? parseDocumentValue(parser, value)
     : typeof value === 'string' ? parser(value) : undefined
   if (parsed === undefined) {
-    if (key === 'validateIssuer') {
+    if (key === 'validateIssuer' || key === 'allowPrivateNetworkAddresses') {
       throw ExceptionHelper.generateException(
         TypeError,
         Errors.InvalidBooleanConfigurationValue,
@@ -598,7 +600,7 @@ export function setConfigurationValue (
     if (parsed.key === 'hosts') {
       ;(target.outboundHostValidator as OutboundHostValidatorConfigurationPatch).hosts = parsed.value as string[]
     } else {
-      ;(target.outboundHostValidator as OutboundHostValidatorConfigurationPatch)[parsed.key as 'enabled' | 'includeDefaultMicrosoftHosts'] = parsed.value as boolean
+      ;(target.outboundHostValidator as OutboundHostValidatorConfigurationPatch)[parsed.key as 'enabled' | 'includeDefaultMicrosoftHosts' | 'allowPrivateNetworkAddresses'] = parsed.value as boolean
     }
     return
   }

package/src/configuration/environmentConfiguration.ts

@@ -256,7 +256,13 @@ function bindOutboundHostValidator (
       emitHierarchySuggestion(sourceName, [parts[0], suggestedProperty].join('__'), true)
     }
   }
-  trySet(layer, `outboundHostValidator.${parts[1]}`, value, sourceName)
+  trySet(
+    layer,
+    `outboundHostValidator.${parts[1]}`,
+    value,
+    sourceName,
+    parts[1].toLowerCase() === 'allowprivatenetworkaddresses'
+  )
 }
 
 function bindAuthorizationHandler (

package/src/connector-client/connectorClient.ts

@@ -53,6 +53,7 @@ export class ConnectorClient {
     this._httpClient = httpClient
   }
 
+  /** Gets the HTTP client used for Connector API requests. */
   public get httpClient (): HttpClient {
     return this._httpClient
   }
@@ -127,6 +128,13 @@ export class ConnectorClient {
     })
   }
 
+  /**
+   * Retrieves a member of a conversation.
+   *
+   * @param userId The member's channel user ID.
+   * @param conversationId The conversation ID.
+   * @returns The member's channel account.
+   */
   public async getConversationMember (userId: string, conversationId: string): Promise<ChannelAccount> {
     return trace(ConnectorClientTraceDefinitions.getConversationMember, async ({ record }) => {
       if (!userId || !conversationId) {

package/src/createCloudAdapter.ts

@@ -15,7 +15,9 @@ import { TurnState } from './app/turnState'
  * Result of creating a CloudAdapter from an agent.
  */
 export interface CloudAdapterResult {
+  /** The adapter to use for processing requests. */
   adapter: CloudAdapter
+  /** The application's outbound header propagation callback, when configured. */
   headerPropagation: HeaderPropagationDefinition | undefined
 }
 

package/src/errorHelper.ts

@@ -3,6 +3,7 @@
 
 import { AgentErrorDefinition } from '@microsoft/agents-activity'
 
+/** Error definitions used by the hosting package. */
 export const Errors: { [key: string]: AgentErrorDefinition } = {
   // ============================================================================
   // TurnContext and Activity Errors (-120000 to -120090)
@@ -295,6 +296,16 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
     description: 'HttpClient requires baseURL when using a relative URL: {url}'
   },
 
+  AttachmentDownloadRedirectLimit: {
+    code: -120292,
+    description: 'Attachment download exceeded the maximum of 50 redirects.'
+  },
+
+  AttachmentDownloadInvalidRedirect: {
+    code: -120293,
+    description: 'Attachment download returned an invalid redirect URL.'
+  },
+
   // ============================================================================
   // Connection and Authentication Errors (-120300 to -120599)
   // ============================================================================

package/src/headerPropagation.ts

@@ -17,14 +17,21 @@ export class HeaderPropagation implements HeaderPropagationCollection {
 
   private _protectedHeaders = ['x-ms-correlation-id']
 
+  /** Gets the normalized headers received on the incoming request. */
   public get incoming (): Record<string, string> {
     return this._incomingRequests
   }
 
+  /** Gets the headers selected for propagation to outgoing requests. */
   public get outgoing (): Record<string, string> {
     return this._outgoingHeaders
   }
 
+  /**
+   * Creates a header propagation collection from incoming request headers.
+   *
+   * @param headers The incoming headers, including optional multi-value headers.
+   */
   constructor (headers: Record<string, string | string[] | undefined>) {
     if (!headers) {
       throw ExceptionHelper.generateException(Error, Errors.HeadersRequired)
@@ -39,6 +46,11 @@ export class HeaderPropagation implements HeaderPropagationCollection {
     this._protectedHeaders = protectedHeaders // Restore protected headers list after propagation
   }
 
+  /**
+   * Copies existing incoming header values to the outgoing collection.
+   *
+   * @param headers The header names to propagate.
+   */
   propagate (headers: string[]) {
     this.process(headers.map(h => [h, '']), key => {
       if (this._incomingRequests[key] && !this._outgoingHeaders[key]) {
@@ -47,6 +59,11 @@ export class HeaderPropagation implements HeaderPropagationCollection {
     })
   }
 
+  /**
+   * Adds headers that do not already exist in either collection.
+   *
+   * @param headers The headers to add.
+   */
   add (headers: Record<string, string>) {
     this.process(Object.entries(headers ?? {}), (key, value) => {
       if (!this._incomingRequests[key] && !this._outgoingHeaders[key]) {
@@ -55,6 +72,11 @@ export class HeaderPropagation implements HeaderPropagationCollection {
     })
   }
 
+  /**
+   * Appends values to headers that already exist in either collection.
+   *
+   * @param headers The values to append.
+   */
   concat (headers: Record<string, string>) {
     this.process(Object.entries(headers ?? {}), (key, value) => {
       if (this._incomingRequests[key] || this._outgoingHeaders[key]) {
@@ -63,12 +85,23 @@ export class HeaderPropagation implements HeaderPropagationCollection {
     })
   }
 
+  /**
+   * Sets outgoing header values unless the headers are protected.
+   *
+   * @param headers The headers to set.
+   */
   override (headers: Record<string, string>) {
     this.process(Object.entries(headers ?? {}), (key, value) => {
       this._outgoingHeaders[key] = value
     })
   }
 
+  /**
+   * Finds a known header name without regard to casing.
+   *
+   * @param key The header name to find.
+   * @returns The original-cased header name, or `undefined` when it is unknown.
+   */
   key (key: string) {
     return this._keys.find(k => k.toLowerCase() === key.toLowerCase())
   }
@@ -113,6 +146,11 @@ export class HeaderPropagation implements HeaderPropagationCollection {
  * A function type that defines how headers should be propagated.
  */
 export interface HeaderPropagationDefinition {
+  /**
+   * Configures outgoing headers for a request.
+   *
+   * @param headers The collection to configure.
+   */
   (headers: HeaderPropagationCollection): void
 }
 

package/src/httpClient.ts

@@ -11,13 +11,21 @@ import { Errors } from './errorHelper'
  * Configuration for an HTTP request.
  */
 export interface HttpRequestConfig {
+  /** The HTTP method. */
   method: string
+  /** The absolute URL or path relative to the client's base URL. */
   url: string
+  /** Headers to merge with the client's default headers. */
   headers?: Record<string, string>
+  /** The request body. */
   data?: unknown
+  /** Query parameters to append to the URL. */
   params?: Record<string, string | undefined>
+  /** The format used to read the response body. */
   responseType?: 'json' | 'arraybuffer' | 'stream'
+  /** The request timeout in milliseconds. */
   timeout?: number
+  /** A signal used to cancel the request. */
   signal?: AbortSignal
 }
 
@@ -25,10 +33,15 @@ export interface HttpRequestConfig {
  * Represents an HTTP response.
  */
 export interface HttpResponse<T = unknown> {
+  /** The parsed response body. */
   data: T
+  /** The HTTP status code. */
   status: number
+  /** The HTTP status text. */
   statusText: string
+  /** The response headers. */
   headers: Headers
+  /** The configuration used for the request. */
   config: HttpRequestConfig
 }
 
@@ -36,7 +49,9 @@ export interface HttpResponse<T = unknown> {
  * Options for creating an HttpClient instance.
  */
 export interface HttpClientOptions {
+  /** The base URL used for relative request URLs. */
   baseURL?: string
+  /** Default headers included with every request. */
   headers?: Record<string, string>
 }
 
@@ -47,27 +62,48 @@ export class HttpClient {
   private _baseURL: string
   private _defaultHeaders: Record<string, string>
 
+  /**
+   * Creates an HTTP client.
+   *
+   * @param options The base URL and default headers.
+   */
   constructor (options: HttpClientOptions = {}) {
     this._baseURL = options.baseURL ?? ''
     this._defaultHeaders = this.normalizeHeaders(options.headers)
   }
 
+  /** Gets the base URL used for relative requests. */
   get baseURL (): string {
     return this._baseURL
   }
 
+  /** Gets the normalized default request headers. */
   get defaultHeaders (): Record<string, string> {
     return this._defaultHeaders
   }
 
+  /** Replaces the default request headers. */
   set defaultHeaders (headers: Record<string, string>) {
     this._defaultHeaders = this.normalizeHeaders(headers)
   }
 
+  /**
+   * Sets a default request header.
+   *
+   * @param name The header name.
+   * @param value The header value.
+   */
   setHeader (name: string, value: string): void {
     this._defaultHeaders[name.toLowerCase()] = value
   }
 
+  /**
+   * Sends an HTTP request.
+   *
+   * @param config The request configuration.
+   * @returns The response with its parsed body.
+   * @throws An {@link HttpError} when the response status is not successful.
+   */
   async request<T = unknown> (config: HttpRequestConfig): Promise<HttpResponse<T>> {
     const url = this.buildUrl(config.url, config.params)
     const headers = this.normalizeHeaders({ ...this._defaultHeaders, ...config.headers })
@@ -142,6 +178,13 @@ export class HttpClient {
     return httpResponse
   }
 
+  /**
+   * Sends an HTTP request, defaulting to GET.
+   *
+   * @param url The absolute URL or path relative to the client's base URL.
+   * @param options Additional request options. The `method` and `url` options override the defaults.
+   * @returns The response with its parsed body.
+   */
   async get<T = unknown> (url: string, options?: Partial<HttpRequestConfig>): Promise<HttpResponse<T>> {
     return this.request<T>({ method: 'get', url, ...options })
   }
@@ -192,10 +235,20 @@ export class HttpClient {
  * Error thrown when an HTTP request fails.
  */
 export class HttpError extends Error {
+  /** The unsuccessful HTTP response. */
   public readonly response: HttpResponse
+  /** The configuration used for the request. */
   public readonly config: HttpRequestConfig
+  /** The HTTP status code. */
   public readonly status: number
 
+  /**
+   * Creates an HTTP request error.
+   *
+   * @param message The error message.
+   * @param response The unsuccessful response.
+   * @param config The request configuration.
+   */
   constructor (message: string, response: HttpResponse, config: HttpRequestConfig) {
     super(message)
     this.name = 'HttpError'
@@ -204,6 +257,11 @@ export class HttpError extends Error {
     this.status = response.status
   }
 
+  /**
+   * Returns a serializable representation of the error.
+   *
+   * @returns The error, request, and response details.
+   */
   toJSON (): Record<string, unknown> {
     return {
       message: this.message,

package/src/interfaces/webResponse.ts

@@ -17,11 +17,17 @@
  * longer needs to import types from `express` at compile time.
  */
 export interface WebResponse {
+  /** Sets the HTTP status code. */
   status (code: number): this
+  /** Sets a response header. */
   setHeader (name: string, value: string): this
+  /** Sends an optional response body. */
   send (body?: unknown): this
+  /** Ends the response. */
   end (): this
+  /** Indicates whether response headers have been sent. */
   headersSent: boolean
+  /** Indicates whether the response stream has ended. */
   writableEnded: boolean
 }
 
@@ -40,5 +46,6 @@ export type NextFunction = (err?: any) => void
  * (`req.params.conversationId`) without coupling to Express's `Request` type.
  */
 export interface WebRequestParamsCarrier {
+  /** Route parameters parsed from the request URL. */
   params?: Record<string, string | undefined>
 }