@microsoft/agents-hosting 0.2.10-g3ac88ff25e → 0.3.5

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

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'
@@ -20,21 +20,47 @@ const TEMP_SCOPE = 'temp'
 
 const SSO_SCOPE = 'sso'
 
+/**
+ * Default interface for conversation state.
+ * Extend this interface to define custom conversation state properties.
+ */
 export interface DefaultConversationState {}
 
+/**
+ * Default interface for user state.
+ * Extend this interface to define custom user state properties.
+ */
 export interface DefaultUserState {}
+
+/**
+ * Default interface for temporary state that persists only during the current turn.
+ * Contains properties used for handling user input, file attachments, and OAuth flows.
+ */
 export interface DefaultTempState {
+  /** Current user input text */
   input: string;
+  /** Collection of files attached to the current message */
   inputFiles: InputFile[];
+  /** Last output text generated by the agent */
   lastOutput: string;
+  /** Results from actions performed by the agent */
   actionOutputs: Record<string, string>;
+  /** OAuth tokens keyed by provider ID */
   authTokens: { [key: string]: string };
+  /** Flag to prevent duplicate token exchanges */
   duplicateTokenExchange?: boolean;
 }
 
+/**
+ * Default interface for Single Sign-On (SSO) state.
+ * Contains properties used for managing OAuth authentication flows.
+ */
 export interface DefaultSSOState {
+  /** Whether an OAuth flow has been started */
   flowStarted: boolean;
+  /** The user's access token */
   userToken: string;
+  /** Expiration timestamp for the current flow */
   flowExpires: number;
 }
 
@@ -67,19 +93,28 @@ export interface DefaultSSOState {
  *   }
  * }
  * ```
+ * @template TConversationState - Type for conversation-scoped state
+ * @template TUserState - Type for user-scoped state
+ * @template TTempState - Type for temporary state that exists only for the current turn
+ * @template TSSOState - Type for Single Sign-On (SSO) state
  */
-
 export class TurnState<
     TConversationState = DefaultConversationState,
     TUserState = DefaultUserState,
     TTempState = DefaultTempState,
     TSSOState = DefaultSSOState
-> implements Memory {
+> implements AppMemory {
   private _scopes: Record<string, TurnStateEntry> = {}
   private _isLoaded = false
   private _loadingPromise?: Promise<boolean>
   private _stateNotLoadedString = 'TurnState hasn\'t been loaded. Call load() first.'
 
+  /**
+   * Gets the conversation-scoped state.
+   * This state is shared by all users in the same conversation.
+   * @returns The conversation state object
+   * @throws Error if state hasn't been loaded
+   */
   public get conversation (): TConversationState {
     const scope = this.getScope(CONVERSATION_SCOPE)
     if (!scope) {
@@ -88,6 +123,11 @@ export class TurnState<
     return scope.value as TConversationState
   }
 
+  /**
+   * Sets the conversation-scoped state.
+   * @param value - The new conversation state object
+   * @throws Error if state hasn't been loaded
+   */
   public set conversation (value: TConversationState) {
     const scope = this.getScope(CONVERSATION_SCOPE)
     if (!scope) {
@@ -96,10 +136,20 @@ export class TurnState<
     scope.replace(value as Record<string, unknown>)
   }
 
+  /**
+   * Gets whether the state has been loaded from storage
+   * @returns True if the state has been loaded, false otherwise
+   */
   public get isLoaded (): boolean {
     return this._isLoaded
   }
 
+  /**
+   * Gets the temporary state for the current turn.
+   * This state is not persisted between turns.
+   * @returns The temporary state object
+   * @throws Error if state hasn't been loaded
+   */
   public get temp (): TTempState {
     const scope = this.getScope(TEMP_SCOPE)
     if (!scope) {
@@ -108,6 +158,11 @@ export class TurnState<
     return scope.value as TTempState
   }
 
+  /**
+   * Sets the temporary state for the current turn.
+   * @param value - The new temporary state object
+   * @throws Error if state hasn't been loaded
+   */
   public set temp (value: TTempState) {
     const scope = this.getScope(TEMP_SCOPE)
     if (!scope) {
@@ -116,6 +171,12 @@ export class TurnState<
     scope.replace(value as Record<string, unknown>)
   }
 
+  /**
+   * Gets the user-scoped state.
+   * This state is unique to each user and persists across conversations.
+   * @returns The user state object
+   * @throws Error if state hasn't been loaded
+   */
   public get user (): TUserState {
     const scope = this.getScope(USER_SCOPE)
     if (!scope) {
@@ -124,6 +185,11 @@ export class TurnState<
     return scope.value as TUserState
   }
 
+  /**
+   * Sets the user-scoped state.
+   * @param value - The new user state object
+   * @throws Error if state hasn't been loaded
+   */
   public set user (value: TUserState) {
     const scope = this.getScope(USER_SCOPE)
     if (!scope) {
@@ -132,6 +198,12 @@ export class TurnState<
     scope.replace(value as Record<string, unknown>)
   }
 
+  /**
+   * Gets the Single Sign-On (SSO) state.
+   * This state is used to manage OAuth authentication flows.
+   * @returns The SSO state object
+   * @throws Error if state hasn't been loaded
+   */
   public get sso (): TSSOState {
     const scope = this.getScope(SSO_SCOPE)
     if (!scope) {
@@ -140,6 +212,11 @@ export class TurnState<
     return scope.value as TSSOState
   }
 
+  /**
+   * Sets the Single Sign-On (SSO) state.
+   * @param value - The new SSO state object
+   * @throws Error if state hasn't been loaded
+   */
   public set sso (value: TSSOState) {
     const scope = this.getScope(SSO_SCOPE)
     if (!scope) {
@@ -148,6 +225,11 @@ export class TurnState<
     scope.replace(value as Record<string, unknown>)
   }
 
+  /**
+   * Marks the conversation state for deletion.
+   * The state will be deleted from storage on the next call to save().
+   * @throws Error if state hasn't been loaded
+   */
   public deleteConversationState (): void {
     const scope = this.getScope(CONVERSATION_SCOPE)
     if (!scope) {
@@ -156,6 +238,11 @@ export class TurnState<
     scope.delete()
   }
 
+  /**
+   * Marks the temporary state for deletion.
+   * Since temporary state is not persisted, this just clears the in-memory object.
+   * @throws Error if state hasn't been loaded
+   */
   public deleteTempState (): void {
     const scope = this.getScope(TEMP_SCOPE)
     if (!scope) {
@@ -164,6 +251,11 @@ export class TurnState<
     scope.delete()
   }
 
+  /**
+   * Marks the user state for deletion.
+   * The state will be deleted from storage on the next call to save().
+   * @throws Error if state hasn't been loaded
+   */
   public deleteUserState (): void {
     const scope = this.getScope(USER_SCOPE)
     if (!scope) {
@@ -172,10 +264,20 @@ export class TurnState<
     scope.delete()
   }
 
+  /**
+   * Gets a specific state scope by name.
+   * @param scope - The name of the scope to retrieve
+   * @returns The state entry for the scope, or undefined if not found
+   */
   public getScope (scope: string): TurnStateEntry | undefined {
     return this._scopes[scope]
   }
 
+  /**
+   * Deletes a value from state by dot-notation path.
+   * Format: "scope.property" or just "property" (defaults to temp scope)
+   * @param path - The path to the value to delete
+   */
   public deleteValue (path: string): void {
     const { scope, name } = this.getScopeAndName(path)
     if (Object.prototype.hasOwnProperty.call(scope.value, name)) {
@@ -183,21 +285,47 @@ export class TurnState<
     }
   }
 
+  /**
+   * Checks if a value exists in state by dot-notation path.
+   * Format: "scope.property" or just "property" (defaults to temp scope)
+   * @param path - The path to check
+   * @returns True if the value exists, false otherwise
+   */
   public hasValue (path: string): boolean {
     const { scope, name } = this.getScopeAndName(path)
     return Object.prototype.hasOwnProperty.call(scope.value, name)
   }
 
+  /**
+   * Gets a value from state by dot-notation path.
+   * Format: "scope.property" or just "property" (defaults to temp scope)
+   * @template TValue - The type of the value to retrieve
+   * @param path - The path to the value
+   * @returns The value at the specified path
+   */
   public getValue<TValue = unknown>(path: string): TValue {
     const { scope, name } = this.getScopeAndName(path)
     return scope.value[name] as TValue
   }
 
+  /**
+   * Sets a value in state by dot-notation path.
+   * Format: "scope.property" or just "property" (defaults to temp scope)
+   * @param path - The path to set
+   * @param value - The value to set
+   */
   public setValue (path: string, value: unknown): void {
     const { scope, name } = this.getScopeAndName(path)
     scope.value[name] = value
   }
 
+  /**
+   * Loads state from storage into memory.
+   * @param context - The turn context
+   * @param storage - Optional storage provider (if not provided, state will be in-memory only)
+   * @param force - If true, forces a reload from storage even if state is already loaded
+   * @returns Promise that resolves to true if state was loaded, false if it was already loaded
+   */
   public load (context: TurnContext, storage?: Storage, force: boolean = false): Promise<boolean> {
     if (this._isLoaded && !force) {
       return Promise.resolve(false)
@@ -242,6 +370,14 @@ export class TurnState<
     return this._loadingPromise
   }
 
+  /**
+   * Saves state changes to storage.
+   * Only changed scopes will be persisted.
+   * @param context - The turn context
+   * @param storage - Optional storage provider (if not provided, state changes won't be persisted)
+   * @returns Promise that resolves when the save operation is complete
+   * @throws Error if state hasn't been loaded
+   */
   public async save (context: TurnContext, storage?: Storage): Promise<void> {
     if (!this._isLoaded && this._loadingPromise) {
       await this._loadingPromise
@@ -291,6 +427,13 @@ export class TurnState<
     }
   }
 
+  /**
+   * Computes the storage keys for each scope based on the turn context.
+   * Override this method in derived classes to add or modify storage keys.
+   * @param context - The turn context
+   * @returns Promise that resolves to a dictionary of scope names to storage keys
+   * @protected
+   */
   protected onComputeStorageKeys (context: TurnContext): Promise<Record<string, string>> {
     const activity = context.activity
     const channelId = activity?.channelId
@@ -321,6 +464,13 @@ export class TurnState<
     return Promise.resolve(keys)
   }
 
+  /**
+   * Parses a dot-notation path into scope and property name.
+   * If no scope is specified, defaults to the temp scope.
+   * @param path - The path to parse (format: "scope.property" or just "property")
+   * @returns Object containing the scope entry and property name
+   * @private
+   */
   private getScopeAndName (path: string): { scope: TurnStateEntry; name: string } {
     const parts = path.split('.')
     if (parts.length > 2) {

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/auth/authConfiguration.ts

@@ -7,13 +7,44 @@
  * Represents the authentication configuration.
  */
 export interface AuthConfiguration {
+  /**
+   * The tenant ID for the authentication configuration.
+   */
   tenantId?: string
+
+  /**
+   * The client ID for the authentication configuration. Required in production.
+   */
   clientId?: string
+
+  /**
+   * The client secret for the authentication configuration.
+   */
   clientSecret?: string
+
+  /**
+   * The path to the certificate PEM file.
+   */
   certPemFile?: string
+
+  /**
+   * The path to the certificate key file.
+   */
   certKeyFile?: string
+
+  /**
+   * A list of valid issuers for the authentication configuration.
+   */
   issuers: string[]
-  connectionName?: string,
+
+  /**
+   * The connection name for the authentication configuration.
+   */
+  connectionName?: string
+
+  /**
+   * The FIC (First-Party Integration Channel) client ID.
+   */
   FICClientId?: string
 }