@microsoft/agents-hosting 1.0.0 → 1.0.7-g73d3d58001

package/src/app/turnState.ts

@@ -40,12 +40,18 @@ export interface DefaultTempState {
 }
 
 /**
- * @summary Base class defining a collection of turn state scopes.
+ * Base class defining a collection of turn state scopes.
+ *
+ * @typeParam TConversationState - Type for conversation-scoped state
+ * @typeParam TUserState - Type for user-scoped state
+ * @typeParam TTempState - Type for temporary state that exists only for the current turn
+ * @typeParam TSSOState - Type for Single Sign-On (SSO) state
+ *
  * @remarks
  * Developers can create a derived class that extends `TurnState` to add additional state scopes.
  *
  * @example
- * ```JavaScript
+ * ```javascript
  * class MyTurnState extends TurnState {
  *   protected async onComputeStorageKeys(context) {
  *     const keys = await super.onComputeStorageKeys(context);
@@ -70,10 +76,7 @@ export interface DefaultTempState {
  *   }
  * }
  * ```
- * @typeParam TConversationState - Type for conversation-scoped state
- * @typeParam TUserState - Type for user-scoped state
- * @typeParam TTempState - Type for temporary state that exists only for the current turn
- * @typeParam TSSOState - Type for Single Sign-On (SSO) state
+ *
  */
 export class TurnState<
     TConversationState = DefaultConversationState,
@@ -87,9 +90,12 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * This state is shared by all users in the same conversation.
    */
   public get conversation (): TConversationState {
     const scope = this.getScope(CONVERSATION_SCOPE)
@@ -101,6 +107,7 @@ export class TurnState<
 
   /**
    * Sets the conversation-scoped state.
+   *
    * @param value - The new conversation state object
    * @throws Error if state hasn't been loaded
    */
@@ -114,6 +121,7 @@ export class TurnState<
 
   /**
    * Gets whether the state has been loaded from storage
+   *
    * @returns True if the state has been loaded, false otherwise
    */
   public get isLoaded (): boolean {
@@ -122,9 +130,12 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * This state is not persisted between turns.
    */
   public get temp (): TTempState {
     const scope = this.getScope(TEMP_SCOPE)
@@ -136,6 +147,7 @@ export class TurnState<
 
   /**
    * Sets the temporary state for the current turn.
+   *
    * @param value - The new temporary state object
    * @throws Error if state hasn't been loaded
    */
@@ -149,9 +161,12 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * This state is unique to each user and persists across conversations.
    */
   public get user (): TUserState {
     const scope = this.getScope(USER_SCOPE)
@@ -163,6 +178,7 @@ export class TurnState<
 
   /**
    * Sets the user-scoped state.
+   *
    * @param value - The new user state object
    * @throws Error if state hasn't been loaded
    */
@@ -176,8 +192,11 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * The state will be deleted from storage on the next call to save().
    */
   public deleteConversationState (): void {
     const scope = this.getScope(CONVERSATION_SCOPE)
@@ -189,8 +208,11 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * Since temporary state is not persisted, this just clears the in-memory object.
    */
   public deleteTempState (): void {
     const scope = this.getScope(TEMP_SCOPE)
@@ -202,8 +224,11 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * The state will be deleted from storage on the next call to save().
    */
   public deleteUserState (): void {
     const scope = this.getScope(USER_SCOPE)
@@ -215,6 +240,7 @@ export class TurnState<
 
   /**
    * 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
    */
@@ -224,8 +250,11 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * Format: "scope.property" or just "property" (defaults to temp scope)
    */
   public deleteValue (path: string): void {
     const { scope, name } = this.getScopeAndName(path)
@@ -236,9 +265,12 @@ 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
+   *
+   * @remarks
+   * Format: "scope.property" or just "property" (defaults to temp scope)
    */
   public hasValue (path: string): boolean {
     const { scope, name } = this.getScopeAndName(path)
@@ -247,10 +279,13 @@ export class TurnState<
 
   /**
    * Gets a value from state by dot-notation path.
-   * Format: "scope.property" or just "property" (defaults to temp scope)
+   *
    * @typeParam TValue - The type of the value to retrieve
    * @param path - The path to the value
    * @returns The value at the specified path
+   *
+   * @remarks
+   * Format: "scope.property" or just "property" (defaults to temp scope)
    */
   public getValue<TValue = unknown>(path: string): TValue {
     const { scope, name } = this.getScopeAndName(path)
@@ -259,9 +294,12 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * Format: "scope.property" or just "property" (defaults to temp scope)
    */
   public setValue (path: string, value: unknown): void {
     const { scope, name } = this.getScopeAndName(path)
@@ -270,6 +308,7 @@ export class TurnState<
 
   /**
    * 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
@@ -321,11 +360,14 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * Only changed scopes will be persisted.
    */
   public async save (context: TurnContext, storage?: Storage): Promise<void> {
     if (!this._isLoaded && this._loadingPromise) {
@@ -378,9 +420,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
+   *
+   * @remarks
+   * Override this method in derived classes to add or modify storage keys.
+   *
    * @protected
    */
   protected onComputeStorageKeys (context: TurnContext): Promise<Record<string, string>> {
@@ -414,9 +460,13 @@ export class TurnState<
 
   /**
    * 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
+   *
+   * @remarks
+   * If no scope is specified, defaults to the temp scope.
+   *
    * @private
    */
   private getScopeAndName (path: string): { scope: TurnStateEntry; name: string } {

package/src/auth/authConfiguration.ts

@@ -48,10 +48,12 @@ export interface AuthConfiguration {
   FICClientId?: string,
 
   /**
-   * Entra Authentication Endpoint to use,  If not populated the Entra Public Cloud endpoint is assumed.
+   * Entra Authentication Endpoint to use.
+   *
+   * @remarks
+   * If not populated the Entra Public Cloud endpoint is assumed.
    * This example of Public Cloud Endpoint is https://login.microsoftonline.com
-   @remarks
-   see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
+   * see also https://learn.microsoft.com/entra/identity-platform/authentication-national-cloud
    */
   authority?: string
 }
@@ -59,6 +61,12 @@ export interface AuthConfiguration {
 /**
  * Loads the authentication configuration from environment variables.
  *
+ * @returns The authentication configuration.
+ * @throws Will throw an error if clientId is not provided in production.
+ *
+ * @remarks
+ * - `clientId` is required
+ *
  * @example
  * ```
  * tenantId=your-tenant-id
@@ -73,10 +81,7 @@ export interface AuthConfiguration {
  * connectionName=your-connection-name
  * authority=your-authority-endpoint
  * ```
- * @remarks
- * - `clientId` is required
- * @returns The authentication configuration.
- * @throws Will throw an error if clientId is not provided in production.
+ *
  */
 export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (cnxName?: string) => {
   if (cnxName === undefined) {
@@ -122,14 +127,16 @@ export const loadAuthConfigFromEnv: (cnxName?: string) => AuthConfiguration = (c
 /**
  * Loads the agent authentication configuration from previous version environment variables.
  *
+ * @returns The agent authentication configuration.
+ * @throws Will throw an error if MicrosoftAppId is not provided in production.
+ *
  * @example
  * ```
  * MicrosoftAppId=your-client-id
  * MicrosoftAppPassword=your-client-secret
  * MicrosoftAppTenantId=your-tenant-id
  * ```
- * @returns The agent authentication configuration.
- * @throws Will throw an error if MicrosoftAppId is not provided in production.
+ *
  */
 export const loadPrevAuthConfigFromEnv: () => AuthConfiguration = () => {
   if (process.env.MicrosoftAppId === undefined && process.env.NODE_ENV === 'production') {

package/src/auth/jwt-middleware.ts

@@ -72,25 +72,32 @@ export const authorizeJWT = (authConfig: AuthConfiguration) => {
   return async function (req: Request, res: Response, next: NextFunction) {
     let failed = false
     logger.debug('authorizing jwt')
-    const authHeader = req.headers.authorization as string
-    if (authHeader) {
-      const token: string = authHeader.split(' ')[1] // Extract the token from the Bearer string
-      try {
-        const user = await verifyToken(token, authConfig)
-        logger.debug('token verified for ', user)
-        req.user = user
-      } catch (err: Error | any) {
-        failed = true
-        logger.error(err)
-        res.status(401).send({ 'jwt-auth-error': err.message })
-      }
+    if (req.method !== 'POST' && req.method !== 'GET') {
+      failed = true
+      logger.warn('Method not allowed', req.method)
+      res.status(405).send({ 'jwt-auth-error': 'Method not allowed' })
     } else {
-      if (!authConfig.clientId && process.env.NODE_ENV !== 'production') {
-        logger.info('using anonymous auth')
-        req.user = { name: 'anonymous' }
+      const authHeader = req.headers.authorization as string
+      if (authHeader) {
+        const token: string = authHeader.split(' ')[1] // Extract the token from the Bearer string
+        try {
+          const user = await verifyToken(token, authConfig)
+          logger.debug('token verified for ', user)
+          req.user = user
+        } catch (err: Error | any) {
+          failed = true
+          logger.error(err)
+          res.status(401).send({ 'jwt-auth-error': err.message })
+        }
       } else {
-        logger.error('authorization header not found')
-        res.status(401).send({ 'jwt-auth-error': 'authorization header not found' })
+        if (!authConfig.clientId && process.env.NODE_ENV !== 'production') {
+          logger.info('using anonymous auth')
+          req.user = { name: 'anonymous' }
+        } else {
+          failed = true
+          logger.error('authorization header not found')
+          res.status(401).send({ 'jwt-auth-error': 'authorization header not found' })
+        }
       }
     }
     if (!failed) {

package/src/cards/adaptiveCard.ts

@@ -11,7 +11,7 @@
  */
 export interface AdaptiveCard {
   /**
-   * The type of the card, which must always be 'AdaptiveCard'.
+   * The type of the card, which must always be `AdaptiveCard`.
    */
   type: 'AdaptiveCard'
   [key: string]: any

package/src/cloudAdapter.ts

@@ -165,6 +165,8 @@ export class CloudAdapter extends BaseAdapter {
           throw new Error('Invalid activity object')
         }
 
+        this.connectorClient = await this.createConnectorClient(activity.serviceUrl, 'https://api.botframework.com')
+
         if (activity.replyToId) {
           response = await this.connectorClient.replyToActivity(activity.conversation.id, activity.replyToId, activity)
         } else {

package/src/headerPropagation.ts

@@ -94,36 +94,48 @@ export interface HeaderPropagationDefinition {
 export interface HeaderPropagationCollection {
   /**
    * The collection of incoming headers from the incoming request.
-   * @remarks This collection is built based on the headers received in the request.
+   *
+   * @remarks
+   * This collection is built based on the headers received in the request.
    */
   incoming: Record<string, string>
   /**
    * The collection of headers that will be propagated to outgoing requests.
-   * @remarks This collection is built based on the incoming headers and the definition provided.
+   *
+   * @remarks
+   * This collection is built based on the incoming headers and the definition provided.
    */
   outgoing: Record<string, string>
   /**
    * Propagates the incoming header value to the outgoing collection based on the header definition key.
    * @param headers List of header keys to propagate.
-   * @remarks If the header does not exist in the incoming headers, it will be ignored.
+   *
+   * @remarks
+   * If the header does not exist in the incoming headers, it will be ignored.
    */
   propagate(headers: string[]): void
   /**
    * Adds a header definition to the outgoing collection.
    * @param headers Headers to add to the outgoing collection.
-   * @remarks If the header already exists, it will not be added.
+   *
+   * @remarks
+   * If the header already exists, it will not be added.
    */
   add(headers: Record<string, string>): void
   /**
    * Concatenates a header definition to the outgoing collection.
    * @param headers Headers to concatenate to the outgoing collection.
-   * @remarks If the header does not exist in the incoming headers, it will be ignored. Unless the header is already present in the outgoing collection.
+   *
+   * @remarks
+   * If the header does not exist in the incoming headers, it will be ignored. Unless the header is already present in the outgoing collection.
    */
   concat(headers: Record<string, string>): void
   /**
    * Overrides a header definition in the outgoing collection.
    * @param headers Headers to override in the outgoing collection.
-   * @remarks If the header does not exist in the incoming headers, it will be added to the outgoing collection.
+   *
+   * @remarks
+   * If the header does not exist in the incoming headers, it will be added to the outgoing collection.
    */
   override(headers: Record<string, string>): void
 }

package/src/index.ts

@@ -25,5 +25,6 @@ export * from './statusCodes'
 export * from './turnContext'
 export * from './turnContextStateCollection'
 export * from './storage/storage'
+export * from './headerPropagation'
 
 export * from './agent-client'

package/src/oauth/userTokenClient.ts

@@ -17,7 +17,6 @@ export class UserTokenClient {
   client: AxiosInstance
   /**
    * Creates a new instance of UserTokenClient.
-   * @param token The token to use for authentication.
    * @param msAppId The Microsoft application ID.
    */
   constructor (private msAppId: string) {
@@ -116,7 +115,8 @@ export class UserTokenClient {
    * Gets the sign-in resource.
    * @param msAppId The application ID.
    * @param connectionName The connection name.
-   * @param activity The activity.
+   * @param conversation The conversation reference.
+   * @param relatesTo Optional. The related conversation reference.
    * @returns A promise that resolves to the signing resource.
    */
   async getSignInResource (msAppId: string, connectionName: string, conversation: ConversationReference, relatesTo?: ConversationReference) : Promise<SignInResource> {

package/src/state/agentState.ts

@@ -13,6 +13,8 @@ const logger = debug('agents:state')
 
 /**
  * Represents agent state that has been cached in the turn context.
+ *
+ * @remarks
  * Used internally to track state changes and avoid unnecessary storage operations.
  */
 export interface CachedAgentState {
@@ -28,6 +30,8 @@ export interface CachedAgentState {
 
 /**
  * Represents a custom key for storing state in a specific location.
+ *
+ * @remarks
  * Allows state to be persisted with channel and conversation identifiers
  * independent of the current context.
  */
@@ -44,7 +48,8 @@ export interface CustomKey {
 }
 
 /**
- * @summary Manages the state of an Agent across turns in a conversation.
+ * Manages the state of an Agent across turns in a conversation.
+ *
  * @remarks
  * AgentState provides functionality to persist and retrieve state data using
  * a storage provider. It handles caching state in the turn context for performance,
@@ -64,10 +69,12 @@ export class AgentState {
 
   /**
    * Creates a property accessor for the specified property.
-   * Property accessors provide typed access to properties within the state object.
    *
    * @param name The name of the property to access
    * @returns A property accessor for the specified property
+   *
+   * @remarks
+   * Property accessors provide typed access to properties within the state object.
    */
   createProperty<T = any>(name: string): AgentStatePropertyAccessor<T> {
     const prop: AgentStatePropertyAccessor<T> = new AgentStatePropertyAccessor<T>(this, name)
@@ -76,12 +83,14 @@ export class AgentState {
 
   /**
    * Loads the state from storage into the turn context.
-   * If state is already cached in the turn context and force is not set, the cached version will be used.
    *
    * @param context The turn context to load state into
    * @param force If true, forces a reload from storage even if state is cached
    * @param customKey Optional custom storage key to use instead of the default
    * @returns A promise that resolves to the loaded state object
+   *
+   * @remarks
+   * If state is already cached in the turn context and force is not set, the cached version will be used.
    */
   public async load (context: TurnContext, force = false, customKey?: CustomKey): Promise<any> {
     const cached: CachedAgentState = context.turnState.get(this.stateKey)
@@ -103,12 +112,14 @@ export class AgentState {
 
   /**
    * Saves the state to storage if it has changed since it was loaded.
-   * Change detection uses a hash of the state object to determine if saving is necessary.
    *
    * @param context The turn context containing the state to save
    * @param force If true, forces a save to storage even if no changes are detected
    * @param customKey Optional custom storage key to use instead of the default
    * @returns A promise that resolves when the save operation is complete
+   *
+   * @remarks
+   * Change detection uses a hash of the state object to determine if saving is necessary.
    */
   public async saveChanges (context: TurnContext, force = false, customKey?: CustomKey): Promise<void> {
     let cached: CachedAgentState = context.turnState.get(this.stateKey)
@@ -151,11 +162,14 @@ export class AgentState {
 
   /**
    * Clears the state by setting it to an empty object in the turn context.
-   * Note: This does not remove the state from storage, it only clears the in-memory representation.
-   * Call saveChanges() after this to persist the empty state to storage.
    *
    * @param context The turn context containing the state to clear
    * @returns A promise that resolves when the clear operation is complete
+   *
+   * @remarks
+   * This does not remove the state from storage, it only clears the in-memory representation.
+   * Call saveChanges() after this to persist the empty state to storage.
+   *
    */
   public async clear (context: TurnContext): Promise<void> {
     const emptyObjectToForceSave = { state: {}, hash: '' }
@@ -193,10 +207,12 @@ export class AgentState {
 
   /**
    * Calculates a hash for the specified state object to detect changes.
-   * The eTag property is excluded from the hash calculation.
    *
    * @param item The state object to calculate the hash for
    * @returns A string hash representing the state
+   *
+   * @remarks
+   * The eTag property is excluded from the hash calculation.
    * @private
    */
   private readonly calculateChangeHash = (item: StoreItem): string => {