@microsoft/agents-hosting 0.5.12-g2d752e9b13 → 0.5.16-g6bdf69cc43

package/dist/src/app/agentApplication.d.ts

@@ -11,26 +11,48 @@ import { AgentApplicationOptions } from './agentApplicationOptions';
 import { AppRoute } from './appRoute';
 import { ConversationUpdateEvents } from './conversationUpdateEvents';
 import { AgentExtension } from './extensions';
-import { Authorization } from './oauth/authorization';
+import { Authorization } from './authorization';
 import { RouteHandler } from './routeHandler';
 import { RouteSelector } from './routeSelector';
 import { TurnEvents } from './turnEvents';
 import { TurnState } from './turnState';
+/**
+ * Event handler function type for application events.
+ * @template TState - The state type extending TurnState.
+ * @param context - The turn context containing activity information.
+ * @param state - The current turn state.
+ * @returns A promise that resolves to a boolean indicating whether to continue execution.
+ */
 export type ApplicationEventHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<boolean>;
 /**
- * Executes the application logic for a given turn context.
+ * Main application class for handling agent conversations and routing.
  *
- * @param turnContext - The context for the current turn of the conversation.
- * @returns A promise that resolves when the application logic has completed.
+ * @template TState - The state type extending TurnState.
  *
  * @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.
+ * The AgentApplication class provides a framework for building conversational agents.
+ * It handles routing activities to appropriate handlers, manages conversation state,
+ * supports authentication flows, and provides various event handling capabilities.
+ *
+ * Key features:
+ * - Activity routing based on type, content, or custom selectors
+ * - State management with automatic load/save
+ * - OAuth authentication support
+ * - Typing indicators and long-running message support
+ * - Extensible architecture with custom extensions
+ * - Event handlers for before/after turn processing
  *
  * Example usage:
  * ```typescript
- * const app = new AgentApplication();
+ * const app = new AgentApplication<MyState>({
+ *   storage: myStorage,
+ *   adapter: myAdapter
+ * });
+ *
+ * app.onMessage('hello', async (context, state) => {
+ *   await context.sendActivity('Hello there!');
+ * });
+ *
  * await app.run(turnContext);
  * ```
  */
@@ -44,22 +66,68 @@ export declare class AgentApplication<TState extends TurnState> {
     private _typingTimer;
     protected readonly _extensions: AgentExtension<TState>[];
     private readonly _adaptiveCards;
-    constructor(options?: Partial<AgentApplicationOptions<TState>>);
     /**
-     * Gets the adapter associated with the application.
-     * @throws Error if the adapter is not configured.
+     * Creates a new instance of AgentApplication.
+     *
+     * @param options - Optional configuration options for the application.
+     *
+     * @remarks
+     * The constructor initializes the application with default settings and applies
+     * any provided options. It sets up the adapter, authorization, and other core
+     * components based on the configuration.
+     *
+     * Default options:
+     * - startTypingTimer: false
+     * - longRunningMessages: false
+     * - removeRecipientMention: true
+     * - turnStateFactory: Creates a new TurnState instance
+     *
+     * Example usage:
+     * ```typescript
+     * const app = new AgentApplication({
+     *   storage: myStorage,
+     *   adapter: myAdapter,
+     *   startTypingTimer: true,
+     *   authorization: { connectionName: 'oauth' }
+     * });
+     * ```
      */
-    get adapter(): BaseAdapter;
+    constructor(options?: Partial<AgentApplicationOptions<TState>>);
     /**
      * Gets the authorization instance for the application.
+     *
+     * @returns The authorization instance.
      * @throws Error if no authentication options were configured.
      */
     get authorization(): Authorization;
     /**
      * Gets the options used to configure the application.
+     *
      * @returns The application options.
      */
     get options(): AgentApplicationOptions<TState>;
+    /**
+     * Gets the adapter used by the application.
+     *
+     * @returns The adapter instance.
+     */
+    get adapter(): BaseAdapter;
+    /**
+     * Gets the adaptive cards actions handler for the application.
+     *
+     * @returns The adaptive cards actions instance.
+     *
+     * @remarks
+     * The adaptive cards actions handler provides functionality for handling
+     * adaptive card interactions, such as submit actions and other card-based events.
+     *
+     * Example usage:
+     * ```typescript
+     * app.adaptiveCards.onSubmit('myCardId', async (context, state, data) => {
+     *   await context.sendActivity(`Received data: ${JSON.stringify(data)}`);
+     * });
+     * ```
+     */
     get adaptiveCards(): AdaptiveCardsActions<TState>;
     /**
      * Sets an error handler for the application.
@@ -85,6 +153,8 @@ export declare 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 authHandlers - Array of authentication handler names for this route. Defaults to empty array.
      * @returns The current instance of the application.
      *
      * @remarks
@@ -100,12 +170,13 @@ export declare class AgentApplication<TState extends TurnState> {
      * );
      * ```
      */
-    addRoute(selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute?: boolean): this;
+    addRoute(selector: RouteSelector, handler: RouteHandler<TState>, isInvokeRoute?: boolean, authHandlers?: string[]): 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.
+     * @param authHandlers - Array of authentication handler names for this activity. Defaults to empty array.
      * @returns The current instance of the application.
      *
      * @remarks
@@ -119,12 +190,13 @@ export declare class AgentApplication<TState extends TurnState> {
      * });
      * ```
      */
-    onActivity(type: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>): this;
+    onActivity(type: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[]): 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.
+     * @param authHandlers - Array of authentication handler names for this event. Defaults to empty array.
      * @returns The current instance of the application.
      * @throws Error if the handler is not a function.
      *
@@ -143,9 +215,10 @@ export declare class AgentApplication<TState extends TurnState> {
      * });
      * ```
      */
-    onConversationUpdate(event: ConversationUpdateEvents, handler: (context: TurnContext, state: TState) => Promise<void>): this;
+    onConversationUpdate(event: ConversationUpdateEvents, handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[]): 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.
@@ -158,6 +231,7 @@ export declare class AgentApplication<TState extends TurnState> {
      * @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.
+     * @param authHandlers - Array of authentication handler names for this message handler. Defaults to empty array.
      * @returns The current instance of the application.
      *
      * @remarks
@@ -172,12 +246,12 @@ export declare class AgentApplication<TState extends TurnState> {
      *   await context.sendActivity('Hello there!');
      * });
      *
-     * app.onMessage(/help., async (context, state) => {
+     * app.onMessage(/help/, async (context, state) => {
      *   await context.sendActivity('How can I help you?');
      * });
      * ```
      */
-    onMessage(keyword: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>): this;
+    onMessage(keyword: string | RegExp | RouteSelector | (string | RegExp | RouteSelector)[], handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[]): this;
     /**
      * Sets a handler to be called when a user successfully signs in.
      *
@@ -196,7 +270,26 @@ export declare class AgentApplication<TState extends TurnState> {
      * });
      * ```
      */
-    onSignInSuccess(handler: (context: TurnContext, state: TurnState, id?: string) => void): this;
+    onSignInSuccess(handler: (context: TurnContext, state: TurnState, id?: string) => Promise<void>): this;
+    /**
+     * Sets a handler to be called when a sign-in attempt fails.
+     *
+     * @param handler - The handler function to be called after a failed sign-in attempt.
+     * @returns The current instance of the application.
+     * @throws Error if authentication options were not configured.
+     *
+     * @remarks
+     * 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:
+     * ```typescript
+     * app.onSignInFailure(async (context, state) => {
+     *   await context.sendActivity('Sign-in failed. Please try again.');
+     * });
+     * ```
+     */
+    onSignInFailure(handler: (context: TurnContext, state: TurnState, id?: string) => Promise<void>): this;
     /**
      * Adds a handler for message reaction added events.
      *
@@ -259,13 +352,33 @@ export declare class AgentApplication<TState extends TurnState> {
     run(turnContext: TurnContext): Promise<void>;
     /**
      * 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.
+     * This is the core internal method that processes a turn in the conversation.
      * It handles routing and executing handlers based on the activity type and content.
+     * While this method is public, it's typically called internally by the `run` method.
+     *
+     * The method performs the following operations:
+     * 1. Starts typing timer if configured
+     * 2. Processes mentions if configured
+     * 3. Loads turn state
+     * 4. Handles authentication flows
+     * 5. Executes before-turn event handlers
+     * 6. Downloads files if file downloaders are configured
+     * 7. Routes to appropriate handlers
+     * 8. Executes after-turn event handlers
+     * 9. Saves turn state
+     *
+     * Example usage:
+     * ```typescript
+     * const handled = await app.runInternal(turnContext);
+     * if (!handled) {
+     *   console.log('No handler matched the activity');
+     * }
+     * ```
      */
     runInternal(turnContext: TurnContext): Promise<boolean>;
     /**
@@ -313,6 +426,26 @@ export declare class AgentApplication<TState extends TurnState> {
      * ```
      */
     startTypingTimer(context: TurnContext): void;
+    /**
+     * Registers an extension with the application.
+     *
+     * @template T - The extension type extending AgentExtension.
+     * @param extension - The extension instance to register.
+     * @param regcb - Callback function called after successful registration.
+     * @throws Error if the extension is already registered.
+     *
+     * @remarks
+     * Extensions provide a way to add custom functionality to the application.
+     * Each extension can only be registered once to prevent conflicts.
+     *
+     * Example usage:
+     * ```typescript
+     * const myExtension = new MyCustomExtension();
+     * app.registerExtension(myExtension, (ext) => {
+     *   console.log('Extension registered:', ext.name);
+     * });
+     * ```
+     */
     registerExtension<T extends AgentExtension<TState>>(extension: T, regcb: (ext: T) => void): void;
     /**
      * Stops the typing indicator timer if it's currently running.
@@ -353,9 +486,42 @@ export declare class AgentApplication<TState extends TurnState> {
      * ```
      */
     onTurn(event: TurnEvents | TurnEvents[], handler: (context: TurnContext, state: TState) => Promise<boolean>): this;
+    /**
+     * Calls a series of event handlers in sequence.
+     *
+     * @param context - The turn context for the current conversation.
+     * @param state - The current turn state.
+     * @param handlers - Array of event handlers to call.
+     * @returns A promise that resolves to true if all handlers returned true, false otherwise.
+     */
     protected callEventHandlers(context: TurnContext, state: TState, handlers: ApplicationEventHandler<TState>[]): Promise<boolean>;
+    /**
+     * Starts a long-running call, potentially in a new conversation context.
+     *
+     * @param context - The turn context for the current conversation.
+     * @param handler - The handler function to execute.
+     * @returns A promise that resolves to the result of the handler.
+     */
     protected startLongRunningCall(context: TurnContext, handler: (context: TurnContext) => Promise<boolean>): Promise<boolean>;
+    /**
+     * Creates a selector function for activity types.
+     *
+     * @param type - The activity type to match. Can be a string, RegExp, or RouteSelector function.
+     * @returns A RouteSelector function that matches the specified activity type.
+     */
     private createActivitySelector;
+    /**
+     * Creates a selector function for conversation update events.
+     *
+     * @param event - The conversation update event to match.
+     * @returns A RouteSelector function that matches the specified conversation update event.
+     */
     private createConversationUpdateSelector;
+    /**
+     * Creates a selector function for message content matching.
+     *
+     * @param keyword - The keyword, pattern, or selector function to match against message text.
+     * @returns A RouteSelector function that matches messages based on the specified keyword.
+     */
     private createMessageSelector;
 }