@microsoft/agents-hosting 0.2.10-g3ac88ff25e → 0.3.5

package/src/auth/request.ts

@@ -13,8 +13,23 @@ export interface Request<
     Body extends Record<string, unknown> = Record<string, unknown>,
     Headers extends Record<string, string[] | string | undefined> = Record<string, string[] | string | undefined>
 > {
+  /**
+   * The body of the HTTP request, containing parsed data.
+   */
   body?: Body
+
+  /**
+   * The headers of the HTTP request, represented as key-value pairs.
+   */
   headers: Headers
+
+  /**
+   * The HTTP method of the request (e.g., GET, POST, PUT, DELETE).
+   */
   method?: string
+
+  /**
+   * The user information extracted from a JWT payload, if available.
+   */
   user?: JwtPayload
 }

package/src/baseAdapter.ts

@@ -20,6 +20,9 @@ const logger = debug('agents:base-adapter')
  * Base class for all adapters, providing middleware and error handling capabilities.
  */
 export abstract class BaseAdapter {
+  /**
+   * The middleware set used to process the pipeline of middleware handlers.
+   */
   protected middleware: MiddlewareSet = new MiddlewareSet()
 
   private turnError: (context: TurnContext, error: Error) => Promise<void> = async (context: TurnContext, error: Error) => {
@@ -42,7 +45,14 @@ export abstract class BaseAdapter {
   readonly ConnectorClientKey = Symbol('ConnectorClient')
   readonly OAuthScopeKey = Symbol('OAuthScope')
 
+  /**
+   * The authentication provider used for token management.
+   */
   authProvider: AuthProvider = new MsalTokenProvider()
+
+  /**
+   * The authentication configuration for the adapter.
+   */
   authConfig: AuthConfiguration = { issuers: [] }
 
   /**
@@ -103,10 +113,18 @@ export abstract class BaseAdapter {
    */
   abstract getAttachment (attachmentId: string, viewId: string): Promise<NodeJS.ReadableStream>
 
+  /**
+   * Gets the error handler for the adapter.
+   * @returns The current error handler function.
+   */
   get onTurnError (): (context: TurnContext, error: Error) => Promise<void> {
     return this.turnError
   }
 
+  /**
+   * Sets the error handler for the adapter.
+   * @param value - The error handler function to set.
+   */
   set onTurnError (value: (context: TurnContext, error: Error) => Promise<void>) {
     this.turnError = value
   }

package/src/cards/cardFactory.ts

@@ -21,6 +21,9 @@ import { SigninCard } from './signinCard'
  * Factory class for creating various types of cards.
  */
 export class CardFactory {
+  /**
+   * The content types supported by the card factory.
+   */
   static contentTypes: any = {
     adaptiveCard: 'application/vnd.microsoft.card.adaptive',
     animationCard: 'application/vnd.microsoft.card.animation',

package/src/cards/index.ts

@@ -15,3 +15,4 @@ export * from './receiptItem'
 export * from './taskModuleAction'
 export * from './thumbnailCard'
 export * from './videoCard'
+export * from './thumbnailUrl'

package/src/cards/o365ConnectorCardActionBase.ts

@@ -3,6 +3,14 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * Defines the possible types of actions in an O365 connector card.
+ *
+ * - `ViewAction`: Represents an action to view content.
+ * - `OpenUri`: Represents an action to open a URI.
+ * - `HttpPOST`: Represents an action to make an HTTP POST request.
+ * - `ActionCard`: Represents an action that opens a card with additional actions or inputs.
+ */
 export type O365ConnectorCardActionType = 'ViewAction' | 'OpenUri' | 'HttpPOST' | 'ActionCard'
 
 /**

package/src/cloudAdapter.ts

@@ -25,15 +25,23 @@ import { normalizeIncomingActivity } from './activityWireCompat'
 const logger = debug('agents:cloud-adapter')
 
 /**
- * Adapter for handling agent interactions.
+ * Adapter for handling agent interactions with various channels through cloud-based services.
+ *
+ * CloudAdapter processes incoming HTTP requests from Microsoft Bot Framework channels,
+ * authenticates them, and generates outgoing responses. It manages the communication
+ * flow between agents and users across different channels, handling activities, attachments,
+ * and conversation continuations.
  */
 export class CloudAdapter extends BaseAdapter {
+  /**
+   * Client for connecting to the Bot Framework Connector service
+   */
   public connectorClient!: ConnectorClient
 
   /**
    * Creates an instance of CloudAdapter.
-   * @param authConfig - The authentication configuration.
-   * @param authProvider - The authentication provider.
+   * @param authConfig - The authentication configuration for securing communications
+   * @param authProvider - Optional custom authentication provider. If not specified, a default MsalTokenProvider will be used
    */
   constructor (authConfig: AuthConfiguration, authProvider?: AuthProvider) {
     super()
@@ -47,6 +55,14 @@ export class CloudAdapter extends BaseAdapter {
     }
   }
 
+  /**
+   * Creates a connector client for a specific service URL and scope.
+   *
+   * @param serviceUrl - The URL of the service to connect to
+   * @param scope - The authentication scope to use
+   * @returns A promise that resolves to a ConnectorClient instance
+   * @protected
+   */
   protected async createConnectorClient (
     serviceUrl: string,
     scope: string
@@ -59,6 +75,12 @@ export class CloudAdapter extends BaseAdapter {
     )
   }
 
+  /**
+   * Sets the connector client on the turn context.
+   *
+   * @param context - The current turn context
+   * @protected
+   */
   protected setConnectorClient (
     context: TurnContext
   ) {
@@ -164,6 +186,9 @@ export class CloudAdapter extends BaseAdapter {
       }
       res.end()
     }
+    if (!request.body) {
+      throw new TypeError('`request.body` parameter required, make sure express.json() is used as middleware')
+    }
     const incoming = normalizeIncomingActivity(request.body!)
     const activity = Activity.fromObject(incoming)
     logger.info(`--> Processing incoming activity, type:${activity.type} channel:${activity.channelId}`)

package/src/getProductInfo.ts

@@ -1,3 +1,10 @@
 import pjson from '@microsoft/agents-hosting/package.json'
 import os from 'os'
+
+/**
+ * Generates a string containing information about the SDK version and runtime environment.
+ * This is used for telemetry and User-Agent headers in HTTP requests.
+ *
+ * @returns A formatted string containing the SDK version, Node.js version, and OS details
+ */
 export const getProductInfo = () : string => `agents-sdk-js/${pjson.version} nodejs/${process.version} ${os.platform()}-${os.arch()}/${os.release()}`

package/src/logger.ts

@@ -1,6 +1,10 @@
 import createDebug, { Debugger } from 'debug'
 
-class Logger {
+/**
+ * Logger class that provides colored logging functionality using the debug package.
+ * Supports different log levels: info, warn, error, and debug.
+ */
+export class Logger {
   private loggers: { [level: string]: Debugger } = {}
   private readonly levelColors: { [level: string]: string } = {
     info: '2', // Green
@@ -9,6 +13,10 @@ class Logger {
     debug: '4' // Blue
   }
 
+  /**
+   * Creates a new Logger instance with the specified namespace.
+   * @param namespace The namespace to use for the logger
+   */
   constructor (namespace: string = '') {
     this.initializeLoggers(namespace)
   }
@@ -21,23 +29,48 @@ class Logger {
     }
   }
 
+  /**
+   * Logs an informational message.
+   * @param message The message to log
+   * @param args Additional arguments to include in the log
+   */
   info (message: string, ...args: any[]) {
     this.loggers.info(message, ...args)
   }
 
+  /**
+   * Logs a warning message.
+   * @param message The message to log
+   * @param args Additional arguments to include in the log
+   */
   warn (message: string, ...args: any[]) {
     this.loggers.warn(message, ...args)
   }
 
+  /**
+   * Logs an error message.
+   * @param message The message to log
+   * @param args Additional arguments to include in the log
+   */
   error (message: string, ...args: any[]) {
     this.loggers.error(message, ...args)
   }
 
+  /**
+   * Logs a debug message.
+   * @param message The message to log
+   * @param args Additional arguments to include in the log
+   */
   debug (message: string, ...args: any[]) {
     this.loggers.debug(message, ...args)
   }
 }
 
+/**
+ * Creates a new Logger instance with the specified namespace.
+ * @param namespace The namespace to use for the logger
+ * @returns A new Logger instance
+ */
 export function debug (namespace: string): Logger {
   return new Logger(namespace)
 }

package/src/oauth/oAuthFlow.ts

@@ -1,14 +1,13 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 import { debug } from './../logger'
-import { Activity, ActivityTypes, Attachment } from '@microsoft/agents-activity'
+import { ActivityTypes, Attachment } from '@microsoft/agents-activity'
 import {
   CardFactory,
   AgentStatePropertyAccessor,
   UserState,
   TurnContext,
   MessageFactory,
-  SigningResource,
   TokenExchangeRequest,
   UserTokenClient
 } from '../'
@@ -25,28 +24,72 @@ interface TokenVerifyState {
   state: string
 }
 /**
- * Manages the OAuth flow for Teams.
+ * Manages the OAuth flow
  */
 export class OAuthFlow {
-  userTokenClient?: UserTokenClient
+  /**
+   * The user token client used for managing user tokens.
+   */
+  userTokenClient: UserTokenClient
+
+  /**
+   * The current state of the OAuth flow.
+   */
   state: FlowState | null
+
+  /**
+   * The accessor for managing the flow state in user state.
+   */
   flowStateAccessor: AgentStatePropertyAccessor<FlowState | null>
+
+  /**
+   * The ID of the token exchange request, used to deduplicate requests.
+   */
   tokenExchangeId: string | null = null
+
+  /**
+   * The name of the OAuth connection.
+   */
   absOauthConnectionName: string
+
+  /**
+   * The title of the OAuth card.
+   */
+  cardTitle: string = 'Sign in'
+
+  /**
+   * The text of the OAuth card.
+   */
+  cardText: string = 'login'
+
   /**
    * Creates a new instance of OAuthFlow.
    * @param userState The user state.
    */
-  constructor (userState: UserState, absOauthConnectionName: string, tokenClient?: UserTokenClient) {
-    this.state = null
+  constructor (userState: UserState, absOauthConnectionName: string, tokenClient?: UserTokenClient, cardTitle?: string, cardText?: string) {
+    this.state = new FlowState()
     this.flowStateAccessor = userState.createProperty('flowState')
     this.absOauthConnectionName = absOauthConnectionName
-    this.userTokenClient = tokenClient
+    this.userTokenClient = tokenClient ?? null!
+    this.cardTitle = cardTitle ?? this.cardTitle
+    this.cardText = cardText ?? this.cardText
   }
 
+  /**
+   * Retrieves the user token from the user token service.
+   * @param context The turn context containing the activity information.
+   * @returns A promise that resolves to the user token response.
+   * @throws Will throw an error if the channelId or from properties are not set in the activity.
+   */
   public async getUserToken (context: TurnContext): Promise<TokenResponse> {
     await this.initializeTokenClient(context)
-    return await this.userTokenClient?.getUserToken(this.absOauthConnectionName, context.activity.channelId!, context.activity.from?.id!)!
+    logger.info('Get token from user token service')
+    const activity = context.activity
+    if (activity.channelId && activity.from && activity.from.id) {
+      return await this.userTokenClient.getUserToken(this.absOauthConnectionName, activity.channelId, activity.from.id)
+    } else {
+      throw new Error('UserTokenService requires channelId and from to be set')
+    }
   }
 
   /**
@@ -55,16 +98,14 @@ export class OAuthFlow {
    * @returns A promise that resolves to the user token.
    */
   public async beginFlow (context: TurnContext): Promise<TokenResponse> {
-    logger.info('Starting OAuth flow')
     this.state = await this.getUserState(context)
-
-    const authConfig = context.adapter.authConfig
     if (this.absOauthConnectionName === '') {
-      throw new Error('connectionName is not set in the auth config, review your environment variables')
+      throw new Error('connectionName is not set')
     }
+    logger.info('Starting OAuth flow for connectionName:', this.absOauthConnectionName)
     await this.initializeTokenClient(context)
 
-    const tokenResponse = await this.userTokenClient!.getUserToken(this.absOauthConnectionName, context.activity.channelId!, context.activity.from?.id!)
+    const tokenResponse = await this.userTokenClient.getUserToken(this.absOauthConnectionName, context.activity.channelId!, context.activity.from?.id!)
     if (tokenResponse?.status === TokenRequestStatus.Success) {
       this.state.flowStarted = false
       this.state.flowExpires = 0
@@ -73,10 +114,10 @@ export class OAuthFlow {
       return tokenResponse
     }
 
-    const signingResource: SigningResource = await this.userTokenClient!.getSignInResource(authConfig.clientId!, this.absOauthConnectionName, context.activity)
-    const oCard: Attachment = CardFactory.oauthCard(this.absOauthConnectionName, 'Sign in', 'login', signingResource)
-    const cardActivity : Activity = MessageFactory.attachment(oCard)
-    await context.sendActivity(cardActivity)
+    const authConfig = context.adapter.authConfig
+    const signingResource = await this.userTokenClient.getSignInResource(authConfig.clientId!, this.absOauthConnectionName, context.activity.getConversationReference(), context.activity.relatesTo)
+    const oCard: Attachment = CardFactory.oauthCard(this.absOauthConnectionName, this.cardTitle, this.cardText, signingResource)
+    await context.sendActivity(MessageFactory.attachment(oCard))
     this.state.flowStarted = true
     this.state.flowExpires = Date.now() + 30000
     await this.flowStateAccessor.set(context, this.state)
@@ -166,7 +207,7 @@ export class OAuthFlow {
   }
 
   private async initializeTokenClient (context: TurnContext) {
-    if (this.userTokenClient === undefined) {
+    if (this.userTokenClient === undefined || this.userTokenClient === null) {
       const scope = 'https://api.botframework.com'
       const accessToken = await context.adapter.authProvider.getAccessToken(context.adapter.authConfig, scope)
       this.userTokenClient = new UserTokenClient(accessToken)

package/src/oauth/userTokenClient.ts

@@ -3,7 +3,7 @@
 
 import axios, { AxiosInstance } from 'axios'
 import { SigningResource } from './signingResource'
-import { Activity } from '@microsoft/agents-activity'
+import { ConversationReference } from '@microsoft/agents-activity'
 import { debug } from '../logger'
 import { TokenExchangeRequest } from './tokenExchangeRequest'
 import { normalizeTokenExchangeState } from '../activityWireCompat'
@@ -86,12 +86,12 @@ export class UserTokenClient {
    * @param activity The activity.
    * @returns A promise that resolves to the signing resource.
    */
-  async getSignInResource (appId: string, cnxName: string, activity: Activity) : Promise<SigningResource> {
+  async getSignInResource (appId: string, cnxName: string, conversationReference: ConversationReference, relatesTo?: ConversationReference) : Promise<SigningResource> {
     try {
       const tokenExchangeState = {
         connectionName: cnxName,
-        conversation: activity.getConversationReference(),
-        relatesTo: activity.RelatesTo,
+        conversation: conversationReference,
+        relatesTo,
         msAppId: appId
       }
       const tokenExchangeStateNormalized = normalizeTokenExchangeState(tokenExchangeState)

package/src/state/agentState.ts

@@ -11,34 +11,63 @@ import { debug } from '../logger'
 
 const logger = debug('agents:state')
 
+/**
+ * Represents agent state that has been cached in the turn context.
+ * Used internally to track state changes and avoid unnecessary storage operations.
+ */
 export interface CachedAgentState {
-  state: { [id: string]: any }
-  hash: string
+  /**
+   * The state object containing all properties and their values
+   */
+  state: { [id: string]: any };
+  /**
+   * Hash of the state used to detect changes
+   */
+  hash: string;
 }
 
+/**
+ * Represents a custom key for storing state in a specific location.
+ * Allows state to be persisted with channel and conversation identifiers
+ * independent of the current context.
+ */
 export interface CustomKey {
+  /**
+   * The ID of the channel where the state should be stored
+   */
   channelId: string;
+  /**
+   * The ID of the conversation where the state should be stored
+   */
   conversationId: string;
   // TODO: namespace needs to be added
 }
 
 /**
- * Manages the state of an Agent.
+ * Manages the state of an Agent across turns in a conversation.
+ *
+ * AgentState provides functionality to persist and retrieve state data using
+ * a storage provider. It handles caching state in the turn context for performance,
+ * calculating change hashes to detect modifications, and managing property accessors
+ * for typed access to state properties.
  */
 export class AgentState {
   private readonly stateKey = Symbol('state')
 
   /**
-    * Creates a new instance of AgentState.
-    * @param storage The storage provider.
-    * @param storageKey The storage key factory.
-    */
+   * Creates a new instance of AgentState.
+   *
+   * @param storage The storage provider used to persist state between turns
+   * @param storageKey A factory function that generates keys for storing state data
+   */
   constructor (protected storage: Storage, protected storageKey: StorageKeyFactory) { }
 
   /**
    * Creates a property accessor for the specified property.
-   * @param name The name of the property.
-   * @returns A property accessor for the specified property.
+   * Property accessors provide typed access to properties within the state object.
+   *
+   * @param name The name of the property to access
+   * @returns A property accessor for the specified property
    */
   createProperty<T = any>(name: string): AgentStatePropertyAccessor<T> {
     const prop: AgentStatePropertyAccessor<T> = new AgentStatePropertyAccessor<T>(this, name)
@@ -46,10 +75,13 @@ export class AgentState {
   }
 
   /**
-   * Loads the state from storage.
-   * @param context The turn context.
-   * @param force Whether to force loading the state.
-   * @returns A promise that resolves to the loaded state.
+   * Loads the state from storage into the turn context.
+   * If state is already cached in the turn context and force is not set, the cached version will be used.
+   *
+   * @param context The turn context to load state into
+   * @param force If true, forces a reload from storage even if state is cached
+   * @param customKey Optional custom storage key to use instead of the default
+   * @returns A promise that resolves to the loaded state object
    */
   public async load (context: TurnContext, force = false, customKey?: CustomKey): Promise<any> {
     const cached: CachedAgentState = context.turnState.get(this.stateKey)
@@ -70,10 +102,13 @@ export class AgentState {
   }
 
   /**
-   * Saves the state to storage.
-   * @param context The turn context.
-   * @param force Whether to force saving the state.
-   * @returns A promise that resolves when the save operation is complete.
+   * Saves the state to storage if it has changed since it was loaded.
+   * Change detection uses a hash of the state object to determine if saving is necessary.
+   *
+   * @param context The turn context containing the state to save
+   * @param force If true, forces a save to storage even if no changes are detected
+   * @param customKey Optional custom storage key to use instead of the default
+   * @returns A promise that resolves when the save operation is complete
    */
   public async saveChanges (context: TurnContext, force = false, customKey?: CustomKey): Promise<void> {
     let cached: CachedAgentState = context.turnState.get(this.stateKey)
@@ -95,6 +130,14 @@ export class AgentState {
     }
   }
 
+  /**
+   * Determines whether to use a custom key or generate one from the context.
+   *
+   * @param customKey Optional custom key with channel and conversation IDs
+   * @param context The turn context used to generate a key if no custom key is provided
+   * @returns The storage key to use
+   * @private
+   */
   private async getStorageOrCustomKey (customKey: CustomKey | undefined, context: TurnContext) {
     let key: string | undefined
     if (customKey && customKey.channelId && customKey.conversationId) {
@@ -107,9 +150,12 @@ export class AgentState {
   }
 
   /**
-   * Clears the state from the turn context.
-   * @param context The turn context.
-   * @returns A promise that resolves when the clear operation is complete.
+   * Clears the state by setting it to an empty object in the turn context.
+   * Note: This does not remove the state from storage, it only clears the in-memory representation.
+   * Call saveChanges() after this to persist the empty state to storage.
+   *
+   * @param context The turn context containing the state to clear
+   * @returns A promise that resolves when the clear operation is complete
    */
   public async clear (context: TurnContext): Promise<void> {
     const emptyObjectToForceSave = { state: {}, hash: '' }
@@ -118,9 +164,11 @@ export class AgentState {
   }
 
   /**
-   * Deletes the state from storage.
-   * @param context The turn context.
-   * @returns A promise that resolves when the delete operation is complete.
+   * Deletes the state from both the turn context and storage.
+   *
+   * @param context The turn context containing the state to delete
+   * @param customKey Optional custom storage key to use instead of the default
+   * @returns A promise that resolves when the delete operation is complete
    */
   public async delete (context: TurnContext, customKey?: CustomKey): Promise<void> {
     if (context.turnState.has(this.stateKey)) {
@@ -132,9 +180,10 @@ export class AgentState {
   }
 
   /**
-   * Gets the state from the turn context.
-   * @param context The turn context.
-   * @returns The state, or undefined if the state is not found.
+   * Gets the state from the turn context without loading it from storage.
+   *
+   * @param context The turn context containing the state to get
+   * @returns The state object, or undefined if no state is found in the turn context
    */
   public get (context: TurnContext): any | undefined {
     const cached: CachedAgentState = context.turnState.get(this.stateKey)
@@ -143,9 +192,12 @@ export class AgentState {
   }
 
   /**
-   * Calculates the change hash for the specified item.
-   * @param item The item to calculate the hash for.
-   * @returns The calculated hash.
+   * Calculates a hash for the specified state object to detect changes.
+   * The eTag property is excluded from the hash calculation.
+   *
+   * @param item The state object to calculate the hash for
+   * @returns A string hash representing the state
+   * @private
    */
   private readonly calculateChangeHash = (item: StoreItem): string => {
     const { eTag, ...rest } = item