@microsoft/agents-hosting 0.2.10-g3ac88ff25e → 0.3.5

package/src/app/agentApplication.ts

@@ -15,28 +15,44 @@ import { AppRoute } from './appRoute'
 import { TurnContext } from '../turnContext'
 import { ResourceResponse } from '../connector-client'
 import { debug } from '../logger'
-import { UserIdentity } from './oauth/userIdentity'
-import { MemoryStorage } from '../storage'
+import { Authorization } from './oauth/authorization'
 
 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>[] = []
   protected readonly _beforeTurn: ApplicationEventHandler<TState>[] = []
   protected readonly _afterTurn: ApplicationEventHandler<TState>[] = []
   private readonly _adapter?: BaseAdapter
+  private readonly _authorization?: Authorization
   private _typingTimer: any
-  private readonly _userIdentity?: UserIdentity
 
   public constructor (options?: Partial<AgentApplicationOptions<TState>>) {
     this._options = {
       ...options,
       turnStateFactory: options?.turnStateFactory || (() => new TurnState() as TState),
-      startTypingTimer: options?.startTypingTimer !== undefined ? options.startTypingTimer : true,
+      startTypingTimer: options?.startTypingTimer !== undefined ? options.startTypingTimer : false,
       longRunningMessages: options?.longRunningMessages !== undefined ? options.longRunningMessages : false
     }
 
@@ -44,8 +60,8 @@ export class AgentApplication<TState extends TurnState> {
       this._adapter = this._options.adapter
     }
 
-    if (this._options.authentication && this._options.authentication.enableSSO && this._options.authentication.ssoConnectionName) {
-      this._userIdentity = new UserIdentity(this._options.storage ?? new MemoryStorage(), this._options.authentication.ssoConnectionName)
+    if (this._options.authorization) {
+      this._authorization = new Authorization(this._options.storage!, this._options.authorization)
     }
 
     if (this._options.longRunningMessages && !this._adapter && !this._options.agentAppId) {
@@ -55,6 +71,10 @@ export class AgentApplication<TState extends TurnState> {
     }
   }
 
+  /**
+   * Gets the adapter associated with the application.
+   * @throws Error if the adapter is not configured.
+   */
   public get adapter (): BaseAdapter {
     if (!this._adapter) {
       throw new Error(
@@ -65,20 +85,46 @@ export class AgentApplication<TState extends TurnState> {
     return this._adapter
   }
 
-  public get userIdentity (): UserIdentity {
-    if (!this._userIdentity) {
+  /**
+   * Gets the authorization instance for the application.
+   * @throws Error if no authentication options were configured.
+   */
+  public get authorization (): Authorization {
+    if (!this._authorization) {
       throw new Error(
-        'The Application.authentication property is unavailable because no authentication options were configured.'
+        'The Application.authorization property is unavailable because no authentication options were configured.'
       )
     }
 
-    return this._userIdentity
+    return this._authorization
   }
 
+  /**
+   * Gets the options used to configure the application.
+   * @returns The application options.
+   */
   public get options (): AgentApplicationOptions<TState> {
     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 +133,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 +187,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 +225,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 +257,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,9 +293,27 @@ export class AgentApplication<TState extends TurnState> {
     return this
   }
 
-  public onSignInSuccess (handler: (context: TurnContext, state: TurnState) => void): this {
-    if (this._userIdentity) {
-      this._userIdentity.onSignInSuccess(handler)
+  /**
+   * 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, id?: string) => void): this {
+    if (this.options.authorization) {
+      this.authorization.onSignInSuccess(handler)
     } else {
       throw new Error(
         'The Application.authentication property is unavailable because no authentication options were configured.'
@@ -165,7 +322,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 +410,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 +445,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 +505,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 +529,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

@@ -7,35 +7,67 @@ import { AgentApplication } from './agentApplication'
 import { AgentApplicationOptions } from './agentApplicationOptions'
 import { TurnState } from './turnState'
 import { Storage } from '../storage'
-import { UserIdentityOptions } from './oauth/userIdentity'
+import { AuthorizationHandlers } from './oauth/authorization'
 
+/**
+ * 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
   }
 
-  public setStartTypingTimer (startTypingTimer: boolean): this {
-    this._options.startTypingTimer = startTypingTimer
-    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
+  // }
 
-  public withAuthentication (authenticationOptions: UserIdentityOptions): this {
-    this._options.authentication = authenticationOptions
+  /**
+   * Sets authentication options for the AgentApplication.
+   * @param authHandlers The user identity authentication options
+   * @returns This builder instance for chaining
+   */
+  public withAuthorization (authHandlers: AuthorizationHandlers): this {
+    this._options.authorization = authHandlers
     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/agentApplicationOptions.ts

@@ -7,15 +7,46 @@ import { CloudAdapter } from '../cloudAdapter'
 import { InputFileDownloader } from './inputFileDownloader'
 import { TurnState } from './turnState'
 import { Storage } from '../storage'
-import { UserIdentityOptions } from './oauth/userIdentity'
+import { AuthorizationHandlers } from './oauth/authorization'
 
 export interface AgentApplicationOptions<TState extends TurnState> {
+  /**
+   * The adapter used for handling bot interactions.
+   */
   adapter?: CloudAdapter;
+
+  /**
+   * The application ID of the agent.
+   */
   agentAppId?: string;
+
+  /**
+   * The storage mechanism for persisting state.
+   */
   storage?: Storage;
+
+  /**
+   * Whether to start a typing timer for the bot.
+   */
   startTypingTimer: boolean;
+
+  /**
+   * Whether to enable long-running messages.
+   */
   longRunningMessages: boolean;
+
+  /**
+   * A factory function to create the turn state.
+   */
   turnStateFactory: () => TState;
+
+  /**
+   * An array of file downloaders for handling input files.
+   */
   fileDownloaders?: InputFileDownloader<TState>[];
-  authentication?: UserIdentityOptions;
+
+  /**
+   * Handlers for managing authorization.
+   */
+  authorization?: AuthorizationHandlers;
 }

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/appRoute.ts

@@ -8,6 +8,13 @@ import { RouteSelector } from './routeSelector'
 import { TurnState } from './turnState'
 
 export interface AppRoute<TState extends TurnState> {
+  /**
+   * The selector function used to determine if this route should handle the current activity.
+   */
   selector: RouteSelector;
+
+  /**
+   * The handler function that processes the activity if the selector matches.
+   */
   handler: RouteHandler<TState>;
 }

package/src/app/attachmentDownloader.ts

@@ -14,13 +14,31 @@ import { loadAuthConfigFromEnv, MsalTokenProvider } from '../auth'
 
 const logger = debug('agents:attachmentDownloader')
 
+/**
+ * A utility class for downloading input files from activity attachments.
+ *
+ * This class provides functionality to filter and download attachments from a turn context,
+ * supporting various content types and handling authentication for secure URLs.
+ *
+ * @typeParam TState - The type of the turn state used in the application.
+ */
 export class AttachmentDownloader<TState extends TurnState = TurnState> implements InputFileDownloader<TState> {
   private _httpClient: AxiosInstance
 
+  /**
+   * Creates an instance of AttachmentDownloader.
+   * This class is responsible for downloading input files from attachments.
+   */
   public constructor () {
     this._httpClient = axios.create()
   }
 
+  /**
+   * Downloads files from the attachments in the current turn context.
+   * @param context The turn context containing the activity with attachments.
+   * @param state The turn state for the current conversation.
+   * @returns A promise that resolves to an array of downloaded input files.
+   */
   public async downloadFiles (context: TurnContext, state: TState): Promise<InputFile[]> {
     const attachments = context.activity.attachments?.filter((a) => !a.contentType.startsWith('text/html'))
     if (!attachments || attachments.length === 0) {

package/src/app/conversationUpdateEvents.ts

@@ -3,6 +3,12 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * Represents the types of conversation update events that can occur.
+ *
+ * - `membersAdded`: Triggered when new members are added to the conversation.
+ * - `membersRemoved`: Triggered when members are removed from the conversation.
+ */
 export type ConversationUpdateEvents =
     | 'membersAdded'
     | 'membersRemoved'

package/src/app/index.ts

@@ -3,9 +3,12 @@ export * from './agentApplicationBuilder'
 export * from './agentApplicationOptions'
 export * from './appRoute'
 export * from './attachmentDownloader'
-export * from './oauth/userIdentity'
+export * from './oauth/authorization'
 export * from './conversationUpdateEvents'
 export * from './routeHandler'
 export * from './routeSelector'
 export * from './turnState'
+export * from './turnEvents'
+export * from './turnStateEntry'
 export * from './inputFileDownloader'
+export * from './appMemory'