@microsoft/agents-hosting 0.2.14 → 0.3.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@microsoft/agents-hosting",
-  "version": "0.2.14",
+  "version": "0.3.5",
   "homepage": "https://github.com/microsoft/Agents-for-js",
   "repository": {
     "type": "git",
@@ -19,9 +19,9 @@
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "dependencies": {
-    "@azure/msal-node": "^3.5.1",
-    "@microsoft/agents-activity": "0.2.14",
-    "axios": "^1.8.2",
+    "@azure/msal-node": "^3.5.2",
+    "@microsoft/agents-activity": "0.3.5",
+    "axios": "^1.9.0",
     "debug": "^4.3.7",
     "jsonwebtoken": "^9.0.2",
     "jwks-rsa": "^3.2.0"

package/src/app/agentApplication.ts

@@ -15,8 +15,7 @@ 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')
 
@@ -46,14 +45,14 @@ export class AgentApplication<TState extends TurnState> {
   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
     }
 
@@ -61,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) {
@@ -72,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(
@@ -82,16 +85,24 @@ 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
   }
@@ -300,9 +311,9 @@ export class AgentApplication<TState extends TurnState> {
    * });
    * ```
    */
-  public onSignInSuccess (handler: (context: TurnContext, state: TurnState) => void): this {
-    if (this._userIdentity) {
-      this._userIdentity.onSignInSuccess(handler)
+  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.'

package/src/app/agentApplicationBuilder.ts

@@ -7,7 +7,7 @@ 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.
@@ -49,18 +49,18 @@ export class AgentApplicationBuilder<TState extends TurnState = TurnState> {
    * @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 setStartTypingTimer (startTypingTimer: boolean): this {
+  //   this._options.startTypingTimer = startTypingTimer
+  //   return this
+  // }
 
   /**
    * Sets authentication options for the AgentApplication.
-   * @param authenticationOptions The user identity authentication options
+   * @param authHandlers The user identity authentication options
    * @returns This builder instance for chaining
    */
-  public withAuthentication (authenticationOptions: UserIdentityOptions): this {
-    this._options.authentication = authenticationOptions
+  public withAuthorization (authHandlers: AuthorizationHandlers): this {
+    this._options.authorization = authHandlers
     return this
   }
 

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/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,7 +3,7 @@ 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'

package/src/app/inputFileDownloader.ts

@@ -6,12 +6,36 @@
 import { TurnContext } from '../turnContext'
 import { TurnState } from './turnState'
 
+/**
+ * Represents a file input with its content, type, and optional URL.
+ */
 export interface InputFile {
+  /**
+   * The content of the file as a Buffer.
+   */
   content: Buffer;
+
+  /**
+   * The MIME type of the file content.
+   */
   contentType: string;
+
+  /**
+   * An optional URL pointing to the file content.
+   */
   contentUrl?: string;
 }
 
+/**
+ * Interface for downloading input files in a specific turn context and state.
+ */
 export interface InputFileDownloader<TState extends TurnState = TurnState> {
+  /**
+   * Downloads files based on the provided turn context and state.
+   *
+   * @param context - The turn context for the current operation.
+   * @param state - The state associated with the current turn.
+   * @returns A promise that resolves to an array of input files.
+   */
   downloadFiles(context: TurnContext, state: TState): Promise<InputFile[]>;
 }

package/src/app/oauth/authorization.ts

@@ -0,0 +1,162 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TurnContext } from '../../turnContext'
+import { debug } from '../../logger'
+import { TurnState } from '../turnState'
+import { Storage } from '../../storage'
+import { OAuthFlow, TokenRequestStatus, TokenResponse } from '../../oauth'
+import { UserState } from '../../state'
+
+const logger = debug('agents:authorization')
+
+/**
+ * Interface defining an authorization handler for OAuth flows
+ * @interface AuthHandler
+ */
+export interface AuthHandler {
+  /** Connection name for the auth provider */
+  name?: string,
+  /** Whether authorization should be triggered automatically */
+  auto?: boolean,
+  /** The OAuth flow implementation */
+  flow?: OAuthFlow,
+  /** Title to display on auth cards/UI */
+  title?: string,
+  /** Text to display on auth cards/UI */
+  text?: string,
+}
+
+/**
+ * Options for configuring user authorization.
+ * Contains settings to configure OAuth connections.
+ */
+export interface AuthorizationHandlers extends Record<string, AuthHandler> {}
+
+/**
+ * Class responsible for managing authorization and OAuth flows
+ * @class Authorization
+ */
+export class Authorization {
+  _authHandlers: AuthorizationHandlers
+
+  /**
+   * Creates a new instance of UserAuthorization.
+   * @param {Storage} storage - The storage system to use for state management.
+   * @param {AuthorizationHandlers} authHandlers - Configuration for OAuth providers
+   * @throws {Error} If storage is null/undefined or no auth handlers are provided
+   */
+  constructor (storage: Storage, authHandlers: AuthorizationHandlers) {
+    if (storage === undefined || storage === null) {
+      throw new Error('Storage is required for UserAuthorization')
+    }
+    const userState = new UserState(storage)
+    if (authHandlers === undefined || Object.keys(authHandlers).length === 0) {
+      throw new Error('The authorization does not have any auth handlers')
+    }
+    this._authHandlers = authHandlers
+    for (const ah in this._authHandlers) {
+      if (this._authHandlers![ah].name === undefined && process.env[ah + '_connectionName'] === undefined) {
+        throw new Error(`AuthHandler name ${ah}_connectionName not set in autorization and not found in env vars.`)
+      }
+      const currentAuthHandler = this._authHandlers![ah]
+      currentAuthHandler.name = currentAuthHandler.name ?? process.env[ah + '_connectionName'] as string
+      currentAuthHandler.title = currentAuthHandler.title ?? process.env[ah + '_connectionTitle'] as string
+      currentAuthHandler.text = currentAuthHandler.text ?? process.env[ah + '_connectionText'] as string
+      currentAuthHandler.auto = currentAuthHandler.auto ?? process.env[ah + '_connectionAuto'] === 'true'
+      currentAuthHandler.flow = new OAuthFlow(userState, currentAuthHandler.name, null!, currentAuthHandler.title, currentAuthHandler.text)
+    }
+    logger.info('Authorization handlers configured with', this._authHandlers.length, 'handlers')
+  }
+
+  /**
+   * Gets the token for a specific auth handler
+   * @param {TurnContext} context - The context object for the current turn
+   * @param {string} [authHandlerId] - Optional ID of the auth handler to use, defaults to first handler
+   * @returns {Promise<TokenResponse>} The token response from the OAuth provider
+   */
+  public async getToken (context: TurnContext, authHandlerId?: string): Promise<TokenResponse> {
+    logger.info('getToken from user token service for authHandlerId:', authHandlerId)
+    const authHandler = this.resolverHandler(authHandlerId)
+    return await authHandler.flow?.getUserToken(context)!
+  }
+
+  /**
+   * Begins or continues an OAuth flow
+   * @param {TurnContext} context - The context object for the current turn
+   * @param {TurnState} state - The state object for the current turn
+   * @param {string} [authHandlerId] - Optional ID of the auth handler to use, defaults to first handler
+   * @returns {Promise<TokenResponse>} The token response from the OAuth provider
+   */
+  public async beginOrContinueFlow (context: TurnContext, state: TurnState, authHandlerId?: string) : Promise<TokenResponse> {
+    logger.info('beginOrContinueFlow for authHandlerId:', authHandlerId)
+    const flow = this.resolverHandler(authHandlerId).flow!
+    let tokenResponse: TokenResponse
+    if (flow.state!.flowStarted === false) {
+      tokenResponse = await flow.beginFlow(context)
+    } else {
+      tokenResponse = await flow.continueFlow(context)
+      if (tokenResponse.status === TokenRequestStatus.Success) {
+        if (this._signInHandler) {
+          await this._signInHandler(context, state, authHandlerId)
+        }
+      }
+    }
+    return tokenResponse
+  }
+
+  /**
+   * Gets the current state of the OAuth flow
+   * @param {string} [authHandlerId] - Optional ID of the auth handler to check, defaults to first handler
+   * @returns {boolean} Whether the flow has started
+   */
+  public getFlowState (authHandlerId?: string) : boolean {
+    const flow = this.resolverHandler(authHandlerId).flow!
+    return flow.state?.flowStarted!
+  }
+
+  /**
+   * Resolves the auth handler to use based on the provided ID
+   * @param {string} [authHandlerId] - Optional ID of the auth handler to resolve, defaults to first handler
+   * @returns {AuthHandler} The resolved auth handler
+   */
+  resolverHandler = (authHandlerId?: string) : AuthHandler => {
+    if (authHandlerId) {
+      return this._authHandlers![authHandlerId]
+    }
+    return this._authHandlers![Object.keys(this._authHandlers)[0]]
+  }
+
+  /**
+   * Signs out the current user.
+   * This method clears the user's token and resets the SSO state.
+   *
+   * @param {TurnContext} context - The context object for the current turn.
+   * @param {TurnState} state - The state object for the current turn.
+   * @param {string} [authHandlerId] - Optional ID of the auth handler to use for sign out
+   * @returns {Promise<void>}
+   */
+  async signOut (context: TurnContext, state: TurnState, authHandlerId?: string) : Promise<void> {
+    logger.info('signOut for authHandlerId:', authHandlerId)
+    if (authHandlerId === undefined) { // aw
+      for (const ah in this._authHandlers) {
+        const flow = this._authHandlers[ah].flow
+        await flow?.signOut(context)
+      }
+    } else {
+      await this.resolverHandler(authHandlerId).flow?.signOut(context)
+    }
+  }
+
+  _signInHandler: ((context: TurnContext, state: TurnState, authHandlerId?: string) => void) | null = null
+
+  /**
+   * Sets a handler to be called when sign-in is successfully completed
+   * @param {Function} handler - The handler function to call on successful sign-in
+   */
+  public onSignInSuccess (handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => void) {
+    this._signInHandler = handler
+  }
+}

package/src/app/routeHandler.ts

@@ -6,4 +6,12 @@
 import { TurnContext } from '../turnContext'
 import { TurnState } from './turnState'
 
+/**
+ * A handler function for routing operations in a specific turn context and state.
+ *
+ * @typeParam TState - The type of the turn state.
+ * @param context - The turn context for the current operation.
+ * @param state - The state associated with the current turn.
+ * @returns A promise that resolves when the routing operation is complete.
+ */
 export type RouteHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<void>

package/src/app/routeSelector.ts

@@ -5,6 +5,15 @@
 
 import { TurnContext } from '../turnContext'
 
+/**
+ * A function that determines whether a specific condition is met in the given turn context.
+ *
+ * @param context - The turn context for the current operation.
+ * @returns A promise that resolves to a boolean indicating whether the condition is met.
+ */
 export type Selector = (context: TurnContext) => Promise<boolean>
 
+/**
+ * A specialized selector for routing operations.
+ */
 export type RouteSelector = Selector