@microsoft/agents-hosting 0.2.14 → 0.3.5

package/src/app/turnState.ts

@@ -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,8 +93,11 @@ 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,
@@ -80,6 +109,12 @@ export class TurnState<
   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/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
 }
 

package/src/auth/request.ts

@@ -13,8 +13,23 @@ export interface Request<
     Body extends Record<string, unknown> = Record<string, unknown>,
     Headers extends Record<string, string[] | string | undefined> = Record<string, string[] | string | undefined>
 > {
+  /**
+   * The body of the HTTP request, containing parsed data.
+   */
   body?: Body
+
+  /**
+   * The headers of the HTTP request, represented as key-value pairs.
+   */
   headers: Headers
+
+  /**
+   * The HTTP method of the request (e.g., GET, POST, PUT, DELETE).
+   */
   method?: string
+
+  /**
+   * The user information extracted from a JWT payload, if available.
+   */
   user?: JwtPayload
 }

package/src/baseAdapter.ts

@@ -20,6 +20,9 @@ const logger = debug('agents:base-adapter')
  * Base class for all adapters, providing middleware and error handling capabilities.
  */
 export abstract class BaseAdapter {
+  /**
+   * The middleware set used to process the pipeline of middleware handlers.
+   */
   protected middleware: MiddlewareSet = new MiddlewareSet()
 
   private turnError: (context: TurnContext, error: Error) => Promise<void> = async (context: TurnContext, error: Error) => {
@@ -42,7 +45,14 @@ export abstract class BaseAdapter {
   readonly ConnectorClientKey = Symbol('ConnectorClient')
   readonly OAuthScopeKey = Symbol('OAuthScope')
 
+  /**
+   * The authentication provider used for token management.
+   */
   authProvider: AuthProvider = new MsalTokenProvider()
+
+  /**
+   * The authentication configuration for the adapter.
+   */
   authConfig: AuthConfiguration = { issuers: [] }
 
   /**
@@ -103,10 +113,18 @@ export abstract class BaseAdapter {
    */
   abstract getAttachment (attachmentId: string, viewId: string): Promise<NodeJS.ReadableStream>
 
+  /**
+   * Gets the error handler for the adapter.
+   * @returns The current error handler function.
+   */
   get onTurnError (): (context: TurnContext, error: Error) => Promise<void> {
     return this.turnError
   }
 
+  /**
+   * Sets the error handler for the adapter.
+   * @param value - The error handler function to set.
+   */
   set onTurnError (value: (context: TurnContext, error: Error) => Promise<void>) {
     this.turnError = value
   }

package/src/cards/cardFactory.ts

@@ -21,6 +21,9 @@ import { SigninCard } from './signinCard'
  * Factory class for creating various types of cards.
  */
 export class CardFactory {
+  /**
+   * The content types supported by the card factory.
+   */
   static contentTypes: any = {
     adaptiveCard: 'application/vnd.microsoft.card.adaptive',
     animationCard: 'application/vnd.microsoft.card.animation',

package/src/cards/o365ConnectorCardActionBase.ts

@@ -3,6 +3,14 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * Defines the possible types of actions in an O365 connector card.
+ *
+ * - `ViewAction`: Represents an action to view content.
+ * - `OpenUri`: Represents an action to open a URI.
+ * - `HttpPOST`: Represents an action to make an HTTP POST request.
+ * - `ActionCard`: Represents an action that opens a card with additional actions or inputs.
+ */
 export type O365ConnectorCardActionType = 'ViewAction' | 'OpenUri' | 'HttpPOST' | 'ActionCard'
 
 /**

package/src/oauth/oAuthFlow.ts

@@ -1,14 +1,13 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 import { debug } from './../logger'
-import { Activity, ActivityTypes, Attachment } from '@microsoft/agents-activity'
+import { ActivityTypes, Attachment } from '@microsoft/agents-activity'
 import {
   CardFactory,
   AgentStatePropertyAccessor,
   UserState,
   TurnContext,
   MessageFactory,
-  SigningResource,
   TokenExchangeRequest,
   UserTokenClient
 } from '../'
@@ -25,28 +24,72 @@ interface TokenVerifyState {
   state: string
 }
 /**
- * Manages the OAuth flow for Teams.
+ * Manages the OAuth flow
  */
 export class OAuthFlow {
-  userTokenClient?: UserTokenClient
+  /**
+   * The user token client used for managing user tokens.
+   */
+  userTokenClient: UserTokenClient
+
+  /**
+   * The current state of the OAuth flow.
+   */
   state: FlowState | null
+
+  /**
+   * The accessor for managing the flow state in user state.
+   */
   flowStateAccessor: AgentStatePropertyAccessor<FlowState | null>
+
+  /**
+   * The ID of the token exchange request, used to deduplicate requests.
+   */
   tokenExchangeId: string | null = null
+
+  /**
+   * The name of the OAuth connection.
+   */
   absOauthConnectionName: string
+
+  /**
+   * The title of the OAuth card.
+   */
+  cardTitle: string = 'Sign in'
+
+  /**
+   * The text of the OAuth card.
+   */
+  cardText: string = 'login'
+
   /**
    * Creates a new instance of OAuthFlow.
    * @param userState The user state.
    */
-  constructor (userState: UserState, absOauthConnectionName: string, tokenClient?: UserTokenClient) {
-    this.state = null
+  constructor (userState: UserState, absOauthConnectionName: string, tokenClient?: UserTokenClient, cardTitle?: string, cardText?: string) {
+    this.state = new FlowState()
     this.flowStateAccessor = userState.createProperty('flowState')
     this.absOauthConnectionName = absOauthConnectionName
-    this.userTokenClient = tokenClient
+    this.userTokenClient = tokenClient ?? null!
+    this.cardTitle = cardTitle ?? this.cardTitle
+    this.cardText = cardText ?? this.cardText
   }
 
+  /**
+   * Retrieves the user token from the user token service.
+   * @param context The turn context containing the activity information.
+   * @returns A promise that resolves to the user token response.
+   * @throws Will throw an error if the channelId or from properties are not set in the activity.
+   */
   public async getUserToken (context: TurnContext): Promise<TokenResponse> {
     await this.initializeTokenClient(context)
-    return await this.userTokenClient?.getUserToken(this.absOauthConnectionName, context.activity.channelId!, context.activity.from?.id!)!
+    logger.info('Get token from user token service')
+    const activity = context.activity
+    if (activity.channelId && activity.from && activity.from.id) {
+      return await this.userTokenClient.getUserToken(this.absOauthConnectionName, activity.channelId, activity.from.id)
+    } else {
+      throw new Error('UserTokenService requires channelId and from to be set')
+    }
   }
 
   /**
@@ -55,16 +98,14 @@ export class OAuthFlow {
    * @returns A promise that resolves to the user token.
    */
   public async beginFlow (context: TurnContext): Promise<TokenResponse> {
-    logger.info('Starting OAuth flow')
     this.state = await this.getUserState(context)
-
-    const authConfig = context.adapter.authConfig
     if (this.absOauthConnectionName === '') {
-      throw new Error('connectionName is not set in the auth config, review your environment variables')
+      throw new Error('connectionName is not set')
     }
+    logger.info('Starting OAuth flow for connectionName:', this.absOauthConnectionName)
     await this.initializeTokenClient(context)
 
-    const tokenResponse = await this.userTokenClient!.getUserToken(this.absOauthConnectionName, context.activity.channelId!, context.activity.from?.id!)
+    const tokenResponse = await this.userTokenClient.getUserToken(this.absOauthConnectionName, context.activity.channelId!, context.activity.from?.id!)
     if (tokenResponse?.status === TokenRequestStatus.Success) {
       this.state.flowStarted = false
       this.state.flowExpires = 0
@@ -73,10 +114,10 @@ export class OAuthFlow {
       return tokenResponse
     }
 
-    const signingResource: SigningResource = await this.userTokenClient!.getSignInResource(authConfig.clientId!, this.absOauthConnectionName, context.activity)
-    const oCard: Attachment = CardFactory.oauthCard(this.absOauthConnectionName, 'Sign in', 'login', signingResource)
-    const cardActivity : Activity = MessageFactory.attachment(oCard)
-    await context.sendActivity(cardActivity)
+    const authConfig = context.adapter.authConfig
+    const signingResource = await this.userTokenClient.getSignInResource(authConfig.clientId!, this.absOauthConnectionName, context.activity.getConversationReference(), context.activity.relatesTo)
+    const oCard: Attachment = CardFactory.oauthCard(this.absOauthConnectionName, this.cardTitle, this.cardText, signingResource)
+    await context.sendActivity(MessageFactory.attachment(oCard))
     this.state.flowStarted = true
     this.state.flowExpires = Date.now() + 30000
     await this.flowStateAccessor.set(context, this.state)
@@ -166,7 +207,7 @@ export class OAuthFlow {
   }
 
   private async initializeTokenClient (context: TurnContext) {
-    if (this.userTokenClient === undefined) {
+    if (this.userTokenClient === undefined || this.userTokenClient === null) {
       const scope = 'https://api.botframework.com'
       const accessToken = await context.adapter.authProvider.getAccessToken(context.adapter.authConfig, scope)
       this.userTokenClient = new UserTokenClient(accessToken)

package/src/oauth/userTokenClient.ts

@@ -3,7 +3,7 @@
 
 import axios, { AxiosInstance } from 'axios'
 import { SigningResource } from './signingResource'
-import { Activity } from '@microsoft/agents-activity'
+import { ConversationReference } from '@microsoft/agents-activity'
 import { debug } from '../logger'
 import { TokenExchangeRequest } from './tokenExchangeRequest'
 import { normalizeTokenExchangeState } from '../activityWireCompat'
@@ -86,12 +86,12 @@ export class UserTokenClient {
    * @param activity The activity.
    * @returns A promise that resolves to the signing resource.
    */
-  async getSignInResource (appId: string, cnxName: string, activity: Activity) : Promise<SigningResource> {
+  async getSignInResource (appId: string, cnxName: string, conversationReference: ConversationReference, relatesTo?: ConversationReference) : Promise<SigningResource> {
     try {
       const tokenExchangeState = {
         connectionName: cnxName,
-        conversation: activity.getConversationReference(),
-        relatesTo: activity.RelatesTo,
+        conversation: conversationReference,
+        relatesTo,
         msAppId: appId
       }
       const tokenExchangeStateNormalized = normalizeTokenExchangeState(tokenExchangeState)

package/src/state/agentStatePropertyAccesor.ts

@@ -84,7 +84,7 @@ export interface StatePropertyAccessor<T = any> {
  * - Type checking for properties (when using TypeScript)
  * - Ensuring properties exist before access
  *
- * Property accessors are created through the AgentState.createProperty() method:
+ * Property accessors are created through the {@link AgentState.createProperty} method:
  *
  * ```typescript
  * // Create a property accessor for a user profile

package/src/statusCodes.ts

@@ -4,17 +4,68 @@
  */
 
 export enum StatusCodes {
+  /**
+   * The request has succeeded.
+   */
   OK = 200,
+
+  /**
+   * The request has been fulfilled and resulted in a new resource being created.
+   */
   CREATED = 201,
+
+  /**
+   * Indicates multiple options for the resource that the client may follow.
+   */
   MULTIPLE_CHOICES = 300,
+
+  /**
+   * The server cannot or will not process the request due to a client error.
+   */
   BAD_REQUEST = 400,
+
+  /**
+   * The request requires user authentication.
+   */
   UNAUTHORIZED = 401,
+
+  /**
+   * The requested resource could not be found.
+   */
   NOT_FOUND = 404,
+
+  /**
+   * The request method is not allowed for the requested resource.
+   */
   METHOD_NOT_ALLOWED = 405,
+
+  /**
+   * The request could not be completed due to a conflict with the current state of the resource.
+   */
   CONFLICT = 409,
+
+  /**
+   * The server does not meet one of the preconditions specified by the client.
+   */
   PRECONDITION_FAILED = 412,
+
+  /**
+   * The client should switch to a different protocol.
+   */
   UPGRADE_REQUIRED = 426,
+
+  /**
+   * The server encountered an unexpected condition that prevented it from fulfilling the request.
+   */
   INTERNAL_SERVER_ERROR = 500,
+
+  /**
+   * The server does not support the functionality required to fulfill the request.
+   */
   NOT_IMPLEMENTED = 501,
+
+  /**
+   * The server received an invalid response from the upstream server.
+   */
   BAD_GATEWAY = 502,
 }