@microsoft/agents-hosting 0.6.1 → 0.6.11

package/src/app/agentApplication.ts

@@ -6,11 +6,10 @@
 import { Activity, ActivityTypes, ConversationReference } from '@microsoft/agents-activity'
 import { BaseAdapter } from '../baseAdapter'
 import { ResourceResponse } from '../connector-client'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { TurnContext } from '../turnContext'
 import { AdaptiveCardsActions } from './adaptiveCards'
 import { AgentApplicationOptions } from './agentApplicationOptions'
-import { AppRoute } from './appRoute'
 import { ConversationUpdateEvents } from './conversationUpdateEvents'
 import { AgentExtension } from './extensions'
 import { Authorization, SignInState } from './authorization'
@@ -18,6 +17,9 @@ import { RouteHandler } from './routeHandler'
 import { RouteSelector } from './routeSelector'
 import { TurnEvents } from './turnEvents'
 import { TurnState } from './turnState'
+import { RouteRank } from './routeRank'
+import { RouteList } from './routeList'
+import { TranscriptLoggerMiddleware } from '../transcript'
 
 const logger = debug('agents:app')
 
@@ -50,10 +52,10 @@ export type ApplicationEventHandler<TState extends TurnState> = (context: TurnCo
  * - Extensible architecture with custom extensions
  * - Event handlers for before/after turn processing
  *
- * Example usage:
+ * @example
  * ```typescript
  * const app = new AgentApplication<MyState>({
- *   storage: myStorage,
+ *   storage: new MemoryStorage(),
  *   adapter: myAdapter
  * });
  *
@@ -66,7 +68,7 @@ export type ApplicationEventHandler<TState extends TurnState> = (context: TurnCo
  */
 export class AgentApplication<TState extends TurnState> {
   protected readonly _options: AgentApplicationOptions<TState>
-  protected readonly _routes: AppRoute<TState>[] = []
+  protected readonly _routes: RouteList<TState> = new RouteList<TState>()
   protected readonly _beforeTurn: ApplicationEventHandler<TState>[] = []
   protected readonly _afterTurn: ApplicationEventHandler<TState>[] = []
   private readonly _adapter?: BaseAdapter
@@ -91,13 +93,14 @@ export class AgentApplication<TState extends TurnState> {
    * - removeRecipientMention: true
    * - turnStateFactory: Creates a new TurnState instance
    *
-   * Example usage:
+   * @example
    * ```typescript
    * const app = new AgentApplication({
-   *   storage: myStorage,
+   *   storage: new MemoryStorage(),
    *   adapter: myAdapter,
    *   startTypingTimer: true,
-   *   authorization: { connectionName: 'oauth' }
+   *   authorization: { connectionName: 'oauth' },
+   *   transcriptLogger: myTranscriptLogger,
    * });
    * ```
    */
@@ -108,6 +111,7 @@ export class AgentApplication<TState extends TurnState> {
       startTypingTimer: options?.startTypingTimer !== undefined ? options.startTypingTimer : false,
       longRunningMessages: options?.longRunningMessages !== undefined ? options.longRunningMessages : false,
       removeRecipientMention: options?.removeRecipientMention !== undefined ? options.removeRecipientMention : true,
+      transcriptLogger: options?.transcriptLogger || undefined,
     }
 
     this._adaptiveCards = new AdaptiveCardsActions<TState>(this)
@@ -123,6 +127,14 @@ export class AgentApplication<TState extends TurnState> {
     if (this._options.longRunningMessages && !this._adapter && !this._options.agentAppId) {
       throw new Error('The Application.longRunningMessages property is unavailable because no adapter was configured in the app.')
     }
+
+    if (this._options.transcriptLogger) {
+      if (!this._options.adapter) {
+        throw new Error('The Application.transcriptLogger property is unavailable because no adapter was configured in the app.')
+      } else {
+        this._adapter?.use(new TranscriptLoggerMiddleware(this._options.transcriptLogger))
+      }
+    }
     logger.debug('AgentApplication created with options:', this._options)
   }
 
@@ -166,9 +178,9 @@ export class AgentApplication<TState extends TurnState> {
    * The adaptive cards actions handler provides functionality for handling
    * adaptive card interactions, such as submit actions and other card-based events.
    *
-   * Example usage:
+   * @example
    * ```typescript
-   * app.adaptiveCards.onSubmit('myCardId', async (context, state, data) => {
+   * app.adaptiveCards.actionSubmit('doStuff', async (context, state, data) => {
    *   await context.sendActivity(`Received data: ${JSON.stringify(data)}`);
    * });
    * ```
@@ -187,7 +199,7 @@ export class AgentApplication<TState extends TurnState> {
    * 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:
+   * @example
    * ```typescript
    * app.onError(async (context, error) => {
    *   console.error(`An error occurred: ${error.message}`);
@@ -208,24 +220,29 @@ export class AgentApplication<TState extends TurnState> {
    * @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.
    * @param isInvokeRoute - Whether this route is for invoke activities. Defaults to false.
+   * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
    * @param authHandlers - Array of authentication handler names for this route. Defaults to empty array.
    * @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.
+   * Routes are evaluated by rank order (if provided), otherwise, in the order they are added.
+   * Invoke-based activities receive special treatment and are matched separately as they typically
+   * have shorter execution timeouts.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * app.addRoute(
    *   async (context) => context.activity.type === ActivityTypes.Message,
    *   async (context, state) => {
    *     await context.sendActivity('I received your message');
-   *   }
+   *   },
+   *   false, // isInvokeRoute
+   *   RouteRank.First // rank
    * );
    * ```
    */
-  public addRoute (selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute: boolean = false, authHandlers: string[] = []): this {
-    this._routes.push({ selector, handler, isInvokeRoute, authHandlers })
+  public addRoute (selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute: boolean = false, rank: number = RouteRank.Unspecified, authHandlers: string[] = []): this {
+    this._routes.addRoute(selector, handler, isInvokeRoute, rank, authHandlers)
     return this
   }
 
@@ -235,13 +252,14 @@ export class AgentApplication<TState extends TurnState> {
    * @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.
    * @param authHandlers - Array of authentication handler names for this activity. Defaults to empty array.
+   * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
    * @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:
+   * @example
    * ```typescript
    * app.onActivity(ActivityTypes.Message, async (context, state) => {
    *   await context.sendActivity('I received your message');
@@ -251,11 +269,12 @@ export class AgentApplication<TState extends TurnState> {
   public onActivity (
     type: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
     handler: (context: TurnContext, state: TState) => Promise<void>,
-    authHandlers: string[] = []
+    authHandlers: string[] = [],
+    rank: RouteRank = RouteRank.Unspecified
   ): this {
     (Array.isArray(type) ? type : [type]).forEach((t) => {
       const selector = this.createActivitySelector(t)
-      this.addRoute(selector, handler, false, authHandlers)
+      this.addRoute(selector, handler, false, rank, authHandlers)
     })
     return this
   }
@@ -266,13 +285,14 @@ export class AgentApplication<TState extends TurnState> {
    * @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.
    * @param authHandlers - Array of authentication handler names for this event. Defaults to empty array.
+   * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
    * @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:
+   * @example
    * ```typescript
    * app.onConversationUpdate('membersAdded', async (context, state) => {
    *   const membersAdded = context.activity.membersAdded;
@@ -287,7 +307,8 @@ export class AgentApplication<TState extends TurnState> {
   public onConversationUpdate (
     event: ConversationUpdateEvents,
     handler: (context: TurnContext, state: TState) => Promise<void>,
-    authHandlers: string[] = []
+    authHandlers: string[] = [],
+    rank: RouteRank = RouteRank.Unspecified
   ): this {
     if (typeof handler !== 'function') {
       throw new Error(
@@ -296,7 +317,7 @@ export class AgentApplication<TState extends TurnState> {
     }
 
     const selector = this.createConversationUpdateSelector(event)
-    this.addRoute(selector, handler, false, authHandlers)
+    this.addRoute(selector, handler, false, rank, authHandlers)
     return this
   }
 
@@ -340,6 +361,7 @@ export class AgentApplication<TState extends TurnState> {
    *                  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.
    * @param authHandlers - Array of authentication handler names for this message handler. Defaults to empty array.
+   * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
    * @returns The current instance of the application.
    *
    * @remarks
@@ -348,13 +370,13 @@ export class AgentApplication<TState extends TurnState> {
    * 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:
+   * @example
    * ```typescript
    * app.onMessage('hello', async (context, state) => {
    *   await context.sendActivity('Hello there!');
    * });
    *
-   * app.onMessage(/help/, async (context, state) => {
+   * app.onMessage(/help/i, async (context, state) => {
    *   await context.sendActivity('How can I help you?');
    * });
    * ```
@@ -362,11 +384,12 @@ export class AgentApplication<TState extends TurnState> {
   public onMessage (
     keyword: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[],
     handler: (context: TurnContext, state: TState) => Promise<void>,
-    authHandlers: string[] = []
+    authHandlers: string[] = [],
+    rank: RouteRank = RouteRank.Unspecified
   ): this {
     (Array.isArray(keyword) ? keyword : [keyword]).forEach((k) => {
       const selector = this.createMessageSelector(k)
-      this.addRoute(selector, handler, false, authHandlers)
+      this.addRoute(selector, handler, false, rank, authHandlers)
     })
     return this
   }
@@ -382,7 +405,7 @@ export class AgentApplication<TState extends TurnState> {
    * This method allows you to perform actions after a user has successfully authenticated.
    * The handler will receive the turn context and state.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * app.onSignInSuccess(async (context, state) => {
    *   await context.sendActivity('You have successfully signed in!');
@@ -411,7 +434,7 @@ export class AgentApplication<TState extends TurnState> {
    * This method allows you to handle cases where a user fails to authenticate,
    * such as when they cancel the sign-in process or an error occurs.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * app.onSignInFailure(async (context, state) => {
    *   await context.sendActivity('Sign-in failed. Please try again.');
@@ -433,13 +456,14 @@ export class AgentApplication<TState extends TurnState> {
    * Adds a handler for message reaction added events.
    *
    * @param handler - The handler function that will be called when a message reaction is added.
+   * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
    * @returns The current instance of the application.
    *
    * @remarks
    * This method registers a handler that will be invoked when a user adds a reaction to a message,
    * such as a like, heart, or other emoji reaction.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * app.onMessageReactionAdded(async (context, state) => {
    *   const reactionsAdded = context.activity.reactionsAdded;
@@ -449,14 +473,16 @@ export class AgentApplication<TState extends TurnState> {
    * });
    * ```
    */
-  public onMessageReactionAdded (handler: (context: TurnContext, state: TState) => Promise<void>): this {
+  public onMessageReactionAdded (
+    handler: (context: TurnContext, state: TState) => Promise<void>,
+    rank: RouteRank = RouteRank.Unspecified): this {
     const selector = async (context: TurnContext): Promise<boolean> => {
       return context.activity.type === ActivityTypes.MessageReaction &&
              Array.isArray(context.activity.reactionsAdded) &&
              context.activity.reactionsAdded.length > 0
     }
 
-    this.addRoute(selector, handler)
+    this.addRoute(selector, handler, false, rank)
     return this
   }
 
@@ -464,13 +490,14 @@ export class AgentApplication<TState extends TurnState> {
    * Adds a handler for message reaction removed events.
    *
    * @param handler - The handler function that will be called when a message reaction is removed.
+   * @param rank - The rank of the route, used to determine the order of evaluation. Defaults to RouteRank.Unspecified.
    * @returns The current instance of the application.
    *
    * @remarks
    * This method registers a handler that will be invoked when a user removes a reaction from a message,
    * such as unliking or removing an emoji reaction.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * app.onMessageReactionRemoved(async (context, state) => {
    *   const reactionsRemoved = context.activity.reactionsRemoved;
@@ -480,14 +507,16 @@ export class AgentApplication<TState extends TurnState> {
    * });
    * ```
    */
-  public onMessageReactionRemoved (handler: (context: TurnContext, state: TState) => Promise<void>): this {
+  public onMessageReactionRemoved (
+    handler: (context: TurnContext, state: TState) => Promise<void>,
+    rank: RouteRank = RouteRank.Unspecified): this {
     const selector = async (context: TurnContext): Promise<boolean> => {
       return context.activity.type === ActivityTypes.MessageReaction &&
              Array.isArray(context.activity.reactionsRemoved) &&
              context.activity.reactionsRemoved.length > 0
     }
 
-    this.addRoute(selector, handler)
+    this.addRoute(selector, handler, false, rank)
     return this
   }
 
@@ -502,7 +531,7 @@ export class AgentApplication<TState extends TurnState> {
    * It delegates the actual processing to the `runInternal` method, which handles
    * the core logic for routing and executing handlers.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * const app = new AgentApplication();
    * await app.run(turnContext);
@@ -534,7 +563,7 @@ export class AgentApplication<TState extends TurnState> {
    * 8. Executes after-turn event handlers
    * 9. Saves turn state
    *
-   * Example usage:
+   * @example
    * ```typescript
    * const handled = await app.runInternal(turnContext);
    * if (!handled) {
@@ -648,7 +677,7 @@ export class AgentApplication<TState extends TurnState> {
    * @remarks
    * This method allows you to send messages proactively to a conversation, outside the normal turn flow.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * // With conversation reference
    * await app.sendProactiveActivity(conversationReference, 'Important notification!');
@@ -685,7 +714,7 @@ export class AgentApplication<TState extends TurnState> {
    * 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:
+   * @example
    * ```typescript
    * app.startTypingTimer(turnContext);
    * // Do some processing...
@@ -743,7 +772,7 @@ export class AgentApplication<TState extends TurnState> {
    * Extensions provide a way to add custom functionality to the application.
    * Each extension can only be registered once to prevent conflicts.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * const myExtension = new MyCustomExtension();
    * app.registerExtension(myExtension, (ext) => {
@@ -769,7 +798,7 @@ export class AgentApplication<TState extends TurnState> {
    * 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:
+   * @example
    * ```typescript
    * app.startTypingTimer(turnContext);
    * // Do some processing...
@@ -795,7 +824,7 @@ export class AgentApplication<TState extends TurnState> {
    * Handlers added for 'beforeTurn' are executed before routing logic.
    * Handlers added for 'afterTurn' are executed after routing logic.
    *
-   * Example usage:
+   * @example
    * ```typescript
    * app.onTurn('beforeTurn', async (context, state) => {
    *   console.log('Processing before turn');

package/src/app/agentApplicationOptions.ts

@@ -5,66 +5,128 @@
 
 import { CloudAdapter } from '../cloudAdapter'
 import { Storage } from '../storage'
+import { TranscriptLogger } from '../transcript'
 import { AdaptiveCardsOptions } from './adaptiveCards'
 import { InputFileDownloader } from './inputFileDownloader'
 import { AuthorizationHandlers } from './authorization'
 import { TurnState } from './turnState'
 
+/**
+ * Configuration options for creating and initializing an Agent Application.
+ * This interface defines all the configurable aspects of an agent's behavior,
+ * including adapter settings, storage, authorization, and various feature flags.
+ *
+ * @template TState - The type of turn state that extends TurnState, allowing for
+ * custom state management specific to your agent's needs.
+ */
 export interface AgentApplicationOptions<TState extends TurnState> {
   /**
-   * The adapter used for handling bot interactions.
+   * The adapter used for handling bot interactions with various messaging platforms.
+   * This adapter manages the communication layer between your agent and the Bot Framework.
+   * If not provided, a default CloudAdapter will be created automatically.
+   *
+   * @default undefined (auto-created)
    */
   adapter?: CloudAdapter;
 
   /**
-   * The application ID of the agent.
+   * The unique application ID of the agent as registered in the Bot Framework.
+   * This ID is used to identify your bot in the Azure Bot Service and should match
+   * the App ID from your bot registration in the Azure portal.
+   *
+   * @example "12345678-1234-1234-1234-123456789012"
    */
   agentAppId?: string;
 
   /**
-   * The storage mechanism for persisting state.
+   * The storage mechanism for persisting conversation and user state across turns.
+   * This can be any implementation of the Storage interface, such as memory storage
+   * for development or blob storage for production scenarios.
+   *
+   * @default undefined (no persistence)
    */
   storage?: Storage;
 
   /**
-   * Whether to start a typing timer for the bot.
+   * Whether to start a typing indicator timer when the bot begins processing a message.
+   * When enabled, users will see a typing indicator while the agent is thinking or processing,
+   * providing better user experience feedback. The typing indicator will automatically stop
+   * when the agent sends a response.
+   *
+   * @default false
    */
   startTypingTimer: boolean;
 
   /**
-   * Whether to enable long-running messages.
+   * Whether to enable support for long-running message processing operations.
+   * When enabled, the agent can handle operations that take longer than the typical
+   * HTTP timeout period without the connection being terminated. This is useful for
+   * complex AI operations, file processing, or external API calls that may take time.
+   *
+   * @default false
    */
   longRunningMessages: boolean;
 
   /**
-   * A factory function to create the turn state.
+   * A factory function that creates a new instance of the turn state for each conversation turn.
+   * This function is called at the beginning of each turn to initialize the state object
+   * that will be used throughout the turn's processing lifecycle.
+   *
+   * @returns A new instance of TState for the current turn
+   * @example () => new MyCustomTurnState()
    */
   turnStateFactory: () => TState;
 
   /**
-   * An array of file downloaders for handling input files.
+   * An array of file downloaders for handling different types of input files from users.
+   * Each downloader can handle specific file types or sources (e.g., SharePoint, OneDrive,
+   * direct uploads). The agent will use these downloaders to process file attachments
+   * sent by users during conversations.
+   *
+   * @default undefined (no file downloading capability)
    */
   fileDownloaders?: InputFileDownloader<TState>[];
 
   /**
-   * Handlers for managing authorization.
+   * Handlers for managing user authentication and authorization within the agent.
+   * This includes OAuth flows, token management, and permission validation.
+   * Use this to implement secure access to protected resources or user-specific data.
+   *
+   * @default undefined (no authorization required)
    */
   authorization?: AuthorizationHandlers;
 
   /**
-   * Options for AdaptiveCard actions.
+   * Configuration options for handling Adaptive Card actions and interactions.
+   * This controls how the agent processes card submissions, button clicks, and other
+   * interactive elements within Adaptive Cards sent to users.
+   *
+   * @default undefined (default Adaptive Card handling)
    */
   adaptiveCardsOptions?: AdaptiveCardsOptions;
 
   /**
-   * Optional. If true, the agent will automatically remove mentions of the bot's name from incoming
-   * messages. Defaults to true.
+   * Whether to automatically remove mentions of the bot's name from incoming messages.
+   * When enabled, if a user mentions the bot by name (e.g., "@BotName hello"), the mention
+   * will be stripped from the message text before processing, leaving just "hello".
+   * This helps create cleaner input for natural language processing.
+   *
+   * @default true
    */
   removeRecipientMention?: boolean;
 
   /**
-   * Optional. If true, the agent will automatically normalize mentions in incoming messages. Defaults to
-   * true.
+   * Whether to automatically normalize mentions in incoming messages.
+   * When enabled, user mentions and other entity mentions in messages will be
+   * standardized to a consistent format, making them easier to process and understand.
+   * This includes formatting @mentions and channel references consistently.
+   *
+   * @default true
    */
   normalizeMentions?: boolean
+
+  /**
+   * Optional. The transcript logger to use for logging conversations. If not provided, no logging will occur.
+   */
+  transcriptLogger?: TranscriptLogger
 }

package/src/app/appRoute.ts

@@ -7,26 +7,81 @@ import { RouteHandler } from './routeHandler'
 import { RouteSelector } from './routeSelector'
 import { TurnState } from './turnState'
 
+/**
+ * Represents a route configuration for handling bot activities within an application.
+ *
+ * @remarks
+ * An AppRoute defines how incoming activities are matched and processed by combining
+ * a selector function that determines when the route should be activated with a handler
+ * function that processes the matched activities.
+ *
+ * @template TState - The type of turn state that extends TurnState, allowing for
+ *                    type-safe access to custom state properties within route handlers
+ *
+ * @example
+ * ```typescript
+ * const echoRoute: AppRoute<MyTurnState> = {
+ *   selector: (activity) => activity.type === 'message',
+ *   handler: async (context, state) => {
+ *     await context.sendActivity(`You said: ${context.activity.text}`);
+ *   }
+ * };
+ * ```
+ */
 export interface AppRoute<TState extends TurnState> {
   /**
    * The selector function used to determine if this route should handle the current activity.
+   *
+   * @remarks
+   * This function is called for each incoming activity to determine if the route's handler
+   * should be invoked. It receives the activity and returns a boolean indicating whether
+   * this route should process the activity.
    */
   selector: RouteSelector;
 
   /**
    * The handler function that processes the activity if the selector matches.
+   *
+   * @remarks
+   * This function contains the core logic for handling the matched activity. It receives
+   * the turn context and state, allowing it to process the activity and respond appropriately.
+   * The handler can be asynchronous and should return a promise that resolves when processing
+   * is complete.
    */
   handler: RouteHandler<TState>;
 
   /**
    * Indicates whether this route is an invoke route.
-   * Invoke routes are used for specific types of activities, such as messaging extensions.
+   *
+   * @remarks
+   * Invoke routes are used for specific types of activities, such as messaging extensions,
+   * adaptive card actions, or other invoke-based interactions. When set to true, this route
+   * will be processed differently than regular message routes, typically with special
+   * handling for invoke responses.
+   *
+   * @default false
    */
   isInvokeRoute?: boolean;
 
+  /**
+   * Optional rank of the route, used to determine the order in which routes are evaluated.
+   * 0 - number.MAX_VALUE. Ranks of the same value are evaluated in order of addition.
+   */
+  rank?: number;
+
   /**
    * Optional list of authorization handlers that this route requires.
-   * If provided, the route will check for these handlers before processing.
+   *
+   * @remarks
+   * If provided, the route will check for these authorization handlers before processing
+   * the activity. Each string in the array should correspond to a registered authorization
+   * handler name. All specified handlers must pass authorization checks before the route
+   * handler is invoked.
+   *
+   * @example
+   * ```typescript
+   * authHandlers: ['oauth', 'admin-only']
+   * ```
    */
   authHandlers?: string[]
 }

package/src/app/attachmentDownloader.ts

@@ -9,7 +9,7 @@ import { TurnState } from './turnState'
 import { TurnContext } from '../turnContext'
 import { Attachment } from '@microsoft/agents-activity'
 import { AuthProvider } from '../auth/authProvider'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { loadAuthConfigFromEnv, MsalTokenProvider } from '../auth'
 
 const logger = debug('agents:attachmentDownloader')
@@ -17,6 +17,7 @@ const logger = debug('agents:attachmentDownloader')
 /**
  * A utility class for downloading input files from activity attachments.
  *
+ * @remarks
  * This class provides functionality to filter and download attachments from a turn context,
  * supporting various content types and handling authentication for secure URLs.
  *

package/src/app/authorization.ts

@@ -4,7 +4,7 @@
  */
 
 import { TurnContext } from '../turnContext'
-import { debug } from '../logger'
+import { debug } from '@microsoft/agents-activity/src/logger'
 import { TurnState } from './turnState'
 import { Storage } from '../storage'
 import { OAuthFlow, TokenResponse } from '../oauth'
@@ -15,7 +15,7 @@ import { Activity } from '@microsoft/agents-activity'
 const logger = debug('agents:authorization')
 
 /**
- * Interface representing the state of a sign-in process.
+ * Represents the state of a sign-in process.
  * @interface SignInState
  */
 export interface SignInState {