@microsoft/agents-hosting 0.2.9-g361635b71c → 0.2.14

package/src/app/agentApplication.ts

@@ -21,8 +21,25 @@ import { MemoryStorage } from '../storage'
 const logger = debug('agents:agent-application')
 
 const TYPING_TIMER_DELAY = 1000
-type ApplicationEventHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<boolean>
+export type ApplicationEventHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<boolean>
 
+/**
+ * Executes the application logic for a given turn context.
+ *
+ * @param turnContext - The context for the current turn of the conversation.
+ * @returns A promise that resolves when the application logic has completed.
+ *
+ * @remarks
+ * This method is the entry point for processing a turn in the conversation.
+ * It delegates the actual processing to the `runInternal` method, which handles
+ * the core logic for routing and executing handlers.
+ *
+ * Example usage:
+ * ```typescript
+ * const app = new AgentApplication();
+ * await app.run(turnContext);
+ * ```
+ */
 export class AgentApplication<TState extends TurnState> {
   protected readonly _options: AgentApplicationOptions<TState>
   protected readonly _routes: AppRoute<TState>[] = []
@@ -79,6 +96,24 @@ export class AgentApplication<TState extends TurnState> {
     return this._options
   }
 
+  /**
+   * Sets an error handler for the application.
+   *
+   * @param handler - The error handler function to be called when an error occurs.
+   * @returns The current instance of the application.
+   *
+   * @remarks
+   * This method allows you to handle any errors that occur during turn processing.
+   * The handler will receive the turn context and the error that occurred.
+   *
+   * Example usage:
+   * ```typescript
+   * app.error(async (context, error) => {
+   *   console.error(`An error occurred: ${error.message}`);
+   *   await context.sendActivity('Sorry, something went wrong!');
+   * });
+   * ```
+   */
   public error (handler: (context: TurnContext, error: Error) => Promise<void>): this {
     if (this._adapter) {
       this._adapter.onTurnError = handler
@@ -87,11 +122,49 @@ export class AgentApplication<TState extends TurnState> {
     return this
   }
 
+  /**
+   * Adds a new route to the application for handling activities.
+   *
+   * @param selector - The selector function that determines if a route should handle the current activity.
+   * @param handler - The handler function that will be called if the selector returns true.
+   * @returns The current instance of the application.
+   *
+   * @remarks
+   * Routes are evaluated in the order they are added. The first route with a selector that returns true will be used.
+   *
+   * Example usage:
+   * ```typescript
+   * app.addRoute(
+   *   async (context) => context.activity.type === ActivityTypes.Message,
+   *   async (context, state) => {
+   *     await context.sendActivity('I received your message');
+   *   }
+   * );
+   * ```
+   */
   public addRoute (selector: RouteSelector, handler: RouteHandler<TState>): this {
     this._routes.push({ selector, handler })
     return this
   }
 
+  /**
+   * Adds a handler for specific activity types.
+   *
+   * @param type - The activity type(s) to handle. Can be a string, RegExp, RouteSelector, or array of these types.
+   * @param handler - The handler function that will be called when the specified activity type is received.
+   * @returns The current instance of the application.
+   *
+   * @remarks
+   * This method allows you to register handlers for specific activity types such as 'message', 'conversationUpdate', etc.
+   * You can specify multiple activity types by passing an array.
+   *
+   * Example usage:
+   * ```typescript
+   * app.activity(ActivityTypes.Message, async (context, state) => {
+   *   await context.sendActivity('I received your message');
+   * });
+   * ```
+   */
   public activity (
     type: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
     handler: (context: TurnContext, state: TState) => Promise<void>
@@ -103,6 +176,29 @@ export class AgentApplication<TState extends TurnState> {
     return this
   }
 
+  /**
+   * Adds a handler for conversation update events.
+   *
+   * @param event - The conversation update event to handle (e.g., 'membersAdded', 'membersRemoved').
+   * @param handler - The handler function that will be called when the specified event occurs.
+   * @returns The current instance of the application.
+   * @throws Error if the handler is not a function.
+   *
+   * @remarks
+   * Conversation update events occur when the state of a conversation changes, such as when members join or leave.
+   *
+   * Example usage:
+   * ```typescript
+   * app.conversationUpdate('membersAdded', async (context, state) => {
+   *   const membersAdded = context.activity.membersAdded;
+   *   for (const member of membersAdded) {
+   *     if (member.id !== context.activity.recipient.id) {
+   *       await context.sendActivity('Hello and welcome!');
+   *     }
+   *   }
+   * });
+   * ```
+   */
   public conversationUpdate (
     event: ConversationUpdateEvents,
     handler: (context: TurnContext, state: TState) => Promise<void>
@@ -118,6 +214,13 @@ export class AgentApplication<TState extends TurnState> {
     return this
   }
 
+  /**
+   * Continues a conversation asynchronously.
+   * @param conversationReferenceOrContext - The conversation reference or turn context.
+   * @param logic - The logic to execute during the conversation.
+   * @returns A promise that resolves when the conversation logic has completed.
+   * @throws Error if the adapter is not configured.
+   */
   protected async continueConversationAsync (
     conversationReferenceOrContext: ConversationReference | TurnContext,
     logic: (context: TurnContext) => Promise<void>
@@ -143,6 +246,31 @@ export class AgentApplication<TState extends TurnState> {
     await this._adapter.continueConversation(reference, logic)
   }
 
+  /**
+   * Adds a handler for message activities that match the specified keyword or pattern.
+   *
+   * @param keyword - The keyword, pattern, or selector function to match against message text.
+   *                  Can be a string, RegExp, RouteSelector, or array of these types.
+   * @param handler - The handler function that will be called when a matching message is received.
+   * @returns The current instance of the application.
+   *
+   * @remarks
+   * This method allows you to register handlers for specific message patterns.
+   * If keyword is a string, it matches messages containing that string.
+   * If keyword is a RegExp, it tests the message text against the regular expression.
+   * If keyword is a function, it calls the function with the context to determine if the message matches.
+   *
+   * Example usage:
+   * ```typescript
+   * app.message('hello', async (context, state) => {
+   *   await context.sendActivity('Hello there!');
+   * });
+   *
+   * app.message(/help., async (context, state) => {
+   *   await context.sendActivity('How can I help you?');
+   * });
+   * ```
+   */
   public message (
     keyword: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
     handler: (context: TurnContext, state: TState) => Promise<void>
@@ -154,6 +282,24 @@ export class AgentApplication<TState extends TurnState> {
     return this
   }
 
+  /**
+   * Sets a handler to be called when a user successfully signs in.
+   *
+   * @param handler - The handler function to be called after successful sign-in.
+   * @returns The current instance of the application.
+   * @throws Error if authentication options were not configured.
+   *
+   * @remarks
+   * This method allows you to perform actions after a user has successfully authenticated.
+   * The handler will receive the turn context and state.
+   *
+   * Example usage:
+   * ```typescript
+   * app.onSignInSuccess(async (context, state) => {
+   *   await context.sendActivity('You have successfully signed in!');
+   * });
+   * ```
+   */
   public onSignInSuccess (handler: (context: TurnContext, state: TurnState) => void): this {
     if (this._userIdentity) {
       this._userIdentity.onSignInSuccess(handler)
@@ -165,7 +311,38 @@ export class AgentApplication<TState extends TurnState> {
     return this
   }
 
-  public async run (turnContext: TurnContext): Promise<boolean> {
+  /**
+   * Executes the application logic for a given turn context.
+   *
+   * @param turnContext - The context for the current turn of the conversation.
+   * @returns A promise that resolves when the application logic has completed.
+   *
+   * @remarks
+   * This method is the entry point for processing a turn in the conversation.
+   * It delegates the actual processing to the `runInternal` method, which handles
+   * the core logic for routing and executing handlers.
+   *
+   * Example usage:
+   * ```typescript
+   * const app = new AgentApplication();
+   * await app.run(turnContext);
+   * ```
+   */
+  public async run (turnContext:TurnContext): Promise<void> {
+    await this.runInternal(turnContext)
+  }
+
+  /**
+   * Executes the application logic for a given turn context.
+   * @private
+   * @param turnContext - The context for the current turn of the conversation.
+   * @returns A promise that resolves to true if a handler was executed, false otherwise.
+   *
+   * @remarks
+   * This method is the core logic for processing a turn in the conversation.
+   * It handles routing and executing handlers based on the activity type and content.
+   */
+  public async runInternal (turnContext: TurnContext): Promise<boolean> {
     return await this.startLongRunningCall(turnContext, async (context) => {
       this.startTypingTimer(context)
       try {
@@ -222,6 +399,27 @@ export class AgentApplication<TState extends TurnState> {
     })
   }
 
+  /**
+   * Sends a proactive message to a conversation.
+   *
+   * @param context - The turn context or conversation reference to use.
+   * @param activityOrText - The activity or text to send.
+   * @param speak - Optional text to be spoken by the bot on a speech-enabled channel.
+   * @param inputHint - Optional input hint for the activity.
+   * @returns A promise that resolves to the resource response from sending the activity.
+   *
+   * @remarks
+   * This method allows you to send messages proactively to a conversation, outside the normal turn flow.
+   *
+   * Example usage:
+   * ```typescript
+   * // With conversation reference
+   * await app.sendProactiveActivity(conversationReference, 'Important notification!');
+   *
+   * // From an existing context
+   * await app.sendProactiveActivity(turnContext, 'Important notification!');
+   * ```
+   */
   public async sendProactiveActivity (
     context: TurnContext | ConversationReference,
     activityOrText: string | Activity,
@@ -236,6 +434,28 @@ export class AgentApplication<TState extends TurnState> {
     return response
   }
 
+  /**
+   * Starts a typing indicator timer for the current turn context.
+   *
+   * @param context - The turn context for the current conversation.
+   * @returns void
+   *
+   * @remarks
+   * This method starts a timer that sends typing activity indicators to the user
+   * at regular intervals. The typing indicator continues until a message is sent
+   * or the timer is explicitly stopped.
+   *
+   * The typing indicator helps provide feedback to users that the agent is processing
+   * their message, especially when responses might take time to generate.
+   *
+   * Example usage:
+   * ```typescript
+   * app.startTypingTimer(turnContext);
+   * // Do some processing...
+   * await turnContext.sendActivity('Response after processing');
+   * // Typing timer automatically stops when sending a message
+   * ```
+   */
   public startTypingTimer (context: TurnContext): void {
     if (context.activity.type === ActivityTypes.Message && !this._typingTimer) {
       let timerRunning = true
@@ -274,6 +494,23 @@ export class AgentApplication<TState extends TurnState> {
     }
   }
 
+  /**
+   * Stops the typing indicator timer if it's currently running.
+   *
+   * @returns void
+   *
+   * @remarks
+   * This method clears the typing indicator timer to prevent further typing indicators
+   * from being sent. It's typically called automatically when a message is sent, but
+   * can also be called manually to stop the typing indicator.
+   *
+   * Example usage:
+   * ```typescript
+   * app.startTypingTimer(turnContext);
+   * // Do some processing...
+   * app.stopTypingTimer(); // Manually stop the typing indicator
+   * ```
+   */
   public stopTypingTimer (): void {
     if (this._typingTimer) {
       clearTimeout(this._typingTimer)
@@ -281,6 +518,26 @@ export class AgentApplication<TState extends TurnState> {
     }
   }
 
+  /**
+   * Adds an event handler for specified turn events.
+   *
+   * @param event - The turn event(s) to handle. Can be 'beforeTurn', 'afterTurn', or other custom events.
+   * @param handler - The handler function that will be called when the event occurs.
+   * @returns The current instance of the application.
+   *
+   * @remarks
+   * Turn events allow you to execute logic before or after the main turn processing.
+   * Handlers added for 'beforeTurn' are executed before routing logic.
+   * Handlers added for 'afterTurn' are executed after routing logic.
+   *
+   * Example usage:
+   * ```typescript
+   * app.turn('beforeTurn', async (context, state) => {
+   *   console.log('Processing before turn');
+   *   return true; // Continue execution
+   * });
+   * ```
+   */
   public turn (
     event: TurnEvents | TurnEvents[],
     handler: (context: TurnContext, state: TState) => Promise<boolean>

package/src/app/agentApplicationBuilder.ts

@@ -9,33 +9,65 @@ import { TurnState } from './turnState'
 import { Storage } from '../storage'
 import { UserIdentityOptions } from './oauth/userIdentity'
 
+/**
+ * Builder class for creating and configuring AgentApplication instances.
+ * @template TState Type extending TurnState that will be used by the application
+ */
 export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
   protected _options: Partial<AgentApplicationOptions<TState>> = {}
 
+  /**
+   * Gets the current options for the AgentApplication being built.
+   * @returns The current options object
+   */
   protected get options () {
     return this._options
   }
 
+  /**
+   * Sets the storage provider for the AgentApplication.
+   * @param storage The storage implementation to use
+   * @returns This builder instance for chaining
+   */
   public withStorage (storage: Storage): this {
     this._options.storage = storage
     return this
   }
 
+  /**
+   * Sets the factory function to create new TurnState instances.
+   * @param turnStateFactory Function that creates a new TurnState
+   * @returns This builder instance for chaining
+   */
   public withTurnStateFactory (turnStateFactory: () => TState): this {
     this._options.turnStateFactory = turnStateFactory
     return this
   }
 
+  /**
+   * Configures whether the agent should display typing indicators.
+   * @param startTypingTimer Whether to show typing indicators
+   * @returns This builder instance for chaining
+   */
   public setStartTypingTimer (startTypingTimer: boolean): this {
     this._options.startTypingTimer = startTypingTimer
     return this
   }
 
+  /**
+   * Sets authentication options for the AgentApplication.
+   * @param authenticationOptions The user identity authentication options
+   * @returns This builder instance for chaining
+   */
   public withAuthentication (authenticationOptions: UserIdentityOptions): this {
     this._options.authentication = authenticationOptions
     return this
   }
 
+  /**
+   * Builds and returns a new AgentApplication instance configured with the provided options.
+   * @returns A new AgentApplication instance
+   */
   public build (): AgentApplication<TState> {
     return new AgentApplication(this._options)
   }

package/src/app/appMemory.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Interface for memory operations that provides a way to store and retrieve values by path.
+ * Allows components to persist state data during a conversation.
+ */
+export interface AppMemory {
+  /**
+   * Deletes a value at the specified path.
+   * @param path The path to the value to delete
+   */
+  deleteValue(path: string): void;
+
+  /**
+   * Checks if a value exists at the specified path.
+   * @param path The path to check
+   * @returns True if a value exists at the path, false otherwise
+   */
+  hasValue(path: string): boolean;
+
+  /**
+   * Gets a value from the specified path.
+   * @template TValue The expected type of the value
+   * @param path The path to get the value from
+   * @returns The value at the specified path cast to type TValue
+   */
+  getValue<TValue = unknown>(path: string): TValue;
+
+  /**
+   * Sets a value at the specified path.
+   * @param path The path where the value should be stored
+   * @param value The value to store
+   */
+  setValue(path: string, value: unknown): void;
+}

package/src/app/index.ts

@@ -8,4 +8,7 @@ export * from './conversationUpdateEvents'
 export * from './routeHandler'
 export * from './routeSelector'
 export * from './turnState'
+export * from './turnEvents'
+export * from './turnStateEntry'
 export * from './inputFileDownloader'
+export * from './appMemory'

package/src/app/turnEvents.ts

@@ -3,4 +3,10 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * Represents the types of events that can occur during a turn in the application.
+ *
+ * - `beforeTurn`: Triggered before the turn starts.
+ * - `afterTurn`: Triggered after the turn ends.
+ */
 export type TurnEvents = 'beforeTurn' | 'afterTurn'

package/src/app/turnState.ts

@@ -4,7 +4,7 @@
  */
 
 import { Storage, StoreItems } from '../storage'
-import { Memory } from './memory'
+import { AppMemory } from './appMemory'
 import { InputFile } from './inputFileDownloader'
 import { TurnStateEntry } from './turnStateEntry'
 import { TurnContext } from '../turnContext'
@@ -74,7 +74,7 @@ export class TurnState<
     TUserState = DefaultUserState,
     TTempState = DefaultTempState,
     TSSOState = DefaultSSOState
-> implements Memory {
+> implements AppMemory {
   private _scopes: Record<string, TurnStateEntry> = {}
   private _isLoaded = false
   private _loadingPromise?: Promise<boolean>

package/src/app/turnStateEntry.ts

@@ -3,26 +3,47 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * Represents an entry in the turn state that can be tracked for changes and stored.
+ */
 export class TurnStateEntry {
   private _value: Record<string, unknown>
   private _storageKey?: string
   private _deleted = false
   private _hash: string
 
+  /**
+   * Creates a new instance of TurnStateEntry.
+   * @param value - The initial value for the entry.
+   * @param storageKey - Optional storage key used to persist the entry.
+   */
   public constructor (value?: Record<string, unknown>, storageKey?: string) {
     this._value = value || {}
     this._storageKey = storageKey
     this._hash = JSON.stringify(this._value)
   }
 
+  /**
+   * Gets whether the entry value has changed since its creation or last update.
+   * @returns True if the value has changed, otherwise false.
+   */
   public get hasChanged (): boolean {
     return JSON.stringify(this._value) !== this._hash
   }
 
+  /**
+   * Gets whether the entry has been marked for deletion.
+   * @returns True if the entry is marked for deletion, otherwise false.
+   */
   public get isDeleted (): boolean {
     return this._deleted
   }
 
+  /**
+   * Gets the current value of the entry. If the entry was marked for deletion,
+   * it will be reset to an empty object and marked as not deleted.
+   * @returns The current value of the entry.
+   */
   public get value (): Record<string, unknown> {
     if (this.isDeleted) {
       this._value = {}
@@ -32,14 +53,25 @@ export class TurnStateEntry {
     return this._value
   }
 
+  /**
+   * Gets the storage key associated with this entry.
+   * @returns The storage key, or undefined if no storage key was specified.
+   */
   public get storageKey (): string | undefined {
     return this._storageKey
   }
 
+  /**
+   * Marks the entry for deletion.
+   */
   public delete (): void {
     this._deleted = true
   }
 
+  /**
+   * Replaces the current value with a new value.
+   * @param value - The new value to set. If undefined, an empty object will be used.
+   */
   public replace (value?: Record<string, unknown>): void {
     this._value = value || {}
   }

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/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()}`