@microsoft/agents-hosting 1.0.0 → 1.0.3-g444d99f704

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/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/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 => {

package/src/state/agentStatePropertyAccesor.ts

@@ -9,29 +9,36 @@ import { AgentState, CustomKey } from './agentState'
 /**
  * Interface for accessing a property in state storage with type safety.
  *
- * The interface defines standard methods for working with persisted state properties,
+ * @typeParam T The type of the property being accessed
+ *
+ * @remarks
+ * This interface defines standard methods for working with persisted state properties,
  * allowing property access with strong typing to reduce errors when working with
  * complex state objects.
  *
- * @typeParam T The type of the property being accessed
  */
 export interface StatePropertyAccessor<T = any> {
   /**
    * Deletes the persisted property from its backing storage object.
    *
+   * @param context Context for the current turn of conversation with the user.
+   *
    * @remarks
    * The properties backing storage object SHOULD be loaded into memory on first access.
    *
-   * ```JavaScript
+   * @example
+   * ```javascript
    * await myProperty.delete(context);
    * ```
-   * @param context Context for the current turn of conversation with the user.
+   *
    */
   delete(context: TurnContext): Promise<void>;
 
   /**
    * Reads a persisted property from its backing storage object.
    *
+   * @param context Context for the current turn of conversation with the user.
+   *
    * @remarks
    * The properties backing storage object SHOULD be loaded into memory on first access.
    *
@@ -39,10 +46,11 @@ export interface StatePropertyAccessor<T = any> {
    * specified, a clone of the `defaultValue` SHOULD be copied to the storage object. If a
    * `defaultValue` has not been specified then a value of `undefined` SHOULD be returned.
    *
-   * ```JavaScript
+   * @example
+   * ```javascript
    * const value = await myProperty.get(context, { count: 0 });
    * ```
-   * @param context Context for the current turn of conversation with the user.
+   *
    */
   get(context: TurnContext): Promise<T | undefined>;
 
@@ -57,26 +65,31 @@ export interface StatePropertyAccessor<T = any> {
   /**
    * Assigns a new value to the properties backing storage object.
    *
+   * @param context Context for the current turn of conversation with the user.
+   * @param value Value to assign.
+   *
    * @remarks
    * The properties backing storage object SHOULD be loaded into memory on first access.
    *
    * Depending on the state systems implementation, an additional step may be required to
    * persist the actual changes to disk.
    *
-   * ```JavaScript
+   * @example
+   * ```javascript
    * await myProperty.set(context, value);
    * ```
-   * @param context Context for the current turn of conversation with the user.
-   * @param value Value to assign.
+   *
    */
   set(context: TurnContext, value: T): Promise<void>;
 }
 
 /**
- * @summary Provides typed access to an Agent state property with automatic state loading and persistence management.
+ * Provides typed access to an Agent state property with automatic state loading and persistence management.
+ *
+ * @typeParam T The type of the property being accessed. Can be any serializable type.
  *
  * @remarks
- * AgentStatePropertyAccessor simplifies working with persisted state by abstracting
+ * `AgentStatePropertyAccessor` simplifies working with persisted state by abstracting
  * the complexity of loading state from storage and manipulating specific properties.
  * It provides a type-safe interface for state management with automatic handling of:
  *
@@ -88,6 +101,11 @@ export interface StatePropertyAccessor<T = any> {
  *
  * ### Key Features
  *
+ * Key features of `AgentStatePropertyAccessor` include:
+ * - [Type Safety](#type-safety)
+ * - [Automatic Default Value Handling](#automatic-default-value-handling)
+ * - [Explicit Persistence Control](#explicit-persistence-control)
+ *
  * #### Type Safety
  * The accessor provides compile-time type checking when using TypeScript:
  * ```typescript
@@ -178,8 +196,6 @@ export interface StatePropertyAccessor<T = any> {
  * - **Persistence**: Always call `state.saveChanges(context)` to persist changes to storage.
  * - **Deep Cloning**: Default values are deep cloned using JSON serialization, which may not work with complex objects containing functions or circular references.
  *
- * @typeParam T The type of the property being accessed. Can be any serializable type.
- *
  * @see {@link AgentState.createProperty} for creating property accessors
  * @see {@link StatePropertyAccessor} for the interface definition
  */
@@ -187,13 +203,13 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   /**
    * Creates a new instance of AgentStatePropertyAccessor.
    *
+   * @param state The agent state object that manages the backing storage for this property
+   * @param name The unique name of the property within the state object. This name is used as the key in the state storage.
+   *
    * @remarks
    * This constructor is typically not called directly. Instead, use {@link AgentState.createProperty}
    * to create property accessors, which ensures proper integration with the state management system.
    *
-   * @param state The agent state object that manages the backing storage for this property
-   * @param name The unique name of the property within the state object. This name is used as the key in the state storage.
-   *
    * @example
    * ```typescript
    * // Recommended way - use AgentState.createProperty
@@ -202,11 +218,18 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * // Direct construction (not recommended)
    * const accessor = new AgentStatePropertyAccessor<UserProfile>(userState, "userProfile");
    * ```
+   *
    */
   constructor (protected readonly state: AgentState, public readonly name: string) { }
 
   /**
-   * @summary Deletes the property from the state storage.
+   * Deletes the property from the state storage.
+   *
+   * @param context The turn context for the current conversation turn
+   * @param customKey Optional custom key for accessing state in a specific storage location.
+   * Useful for multi-tenant scenarios or when state needs to be partitioned.
+   * @returns A promise that resolves when the delete operation is complete
+   *
    * @remarks
    * This operation removes the property from the in-memory state object but does not
    * automatically persist the change to the underlying storage. You must call
@@ -216,13 +239,7 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * - The deletion only affects the in-memory state until `saveChanges()` is called
    * - After deletion, subsequent `get()` calls will return `undefined` (or the default value if provided)
    *
-   * @param context The turn context for the current conversation turn
-   * @param customKey Optional custom key for accessing state in a specific storage location.
-   * Useful for multi-tenant scenarios or when state needs to be partitioned.
-   *
-   * @returns A promise that resolves when the delete operation is complete
-   *
-   * @example
+   * @example Basic usage
    * ```typescript
    * const userSettings = userState.createProperty<UserSettings>("settings");
    *
@@ -242,6 +259,7 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * await userSettings.delete(context, tenantKey);
    * await userState.saveChanges(context);
    * ```
+   *
    */
   async delete (context: TurnContext, customKey?: CustomKey): Promise<void> {
     const obj: any = await this.state.load(context, false, customKey)
@@ -251,7 +269,16 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   }
 
   /**
-   * @summary Retrieves the value of the property from state storage.
+   * Retrieves the value of the property from state storage.
+   *
+   * @param context The turn context for the current conversation turn
+   * @param defaultValue Optional default value to use if the property doesn't exist.
+   *                    When provided, this value is deep cloned and stored in state.
+   * @param customKey Optional custom key for accessing state in a specific storage location.
+   *                  Useful for multi-tenant scenarios or when state needs to be partitioned.
+   *
+   * @returns A promise that resolves to the property value, the cloned default value, or `undefined`
+   *
    * @remarks
    * This method provides intelligent default value handling:
    * - If the property exists, its value is returned
@@ -268,14 +295,6 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * **Performance**: The first access loads state from storage; subsequent accesses use
    * the in-memory cached version until the context is disposed.
    *
-   * @param context The turn context for the current conversation turn
-   * @param defaultValue Optional default value to use if the property doesn't exist.
-   *                    When provided, this value is deep cloned and stored in state.
-   * @param customKey Optional custom key for accessing state in a specific storage location.
-   *                  Useful for multi-tenant scenarios or when state needs to be partitioned.
-   *
-   * @returns A promise that resolves to the property value, the cloned default value, or `undefined`
-   *
    * @example Basic usage
    * ```typescript
    * const counterProperty = userState.createProperty<number>("counter");
@@ -314,6 +333,7 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * const tenantKey = { key: `tenant_${tenantId}` };
    * const tenantData = await dataProperty.get(context, defaultData, tenantKey);
    * ```
+   *
    */
   async get (context: TurnContext, defaultValue?: T, customKey?: CustomKey): Promise<T> {
     const obj: any = await this.state.load(context, false, customKey)
@@ -329,7 +349,15 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
   }
 
   /**
-   * @summary Sets the value of the property in state storage.
+   * Sets the value of the property in state storage.
+   *
+   * @param context The turn context for the current conversation turn
+   * @param value The value to assign to the property. Can be any serializable value.
+   * @param customKey Optional custom key for accessing state in a specific storage location.
+   *                  Useful for multi-tenant scenarios or when state needs to be partitioned.
+   *
+   * @returns A promise that resolves when the set operation is complete
+   *
    * @remarks
    * This operation updates the property in the in-memory state object but does not
    * automatically persist the change to the underlying storage. You must call
@@ -346,13 +374,6 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * **Type Safety**: When using TypeScript, the value must match the property's
    * declared type parameter.
    *
-   * @param context The turn context for the current conversation turn
-   * @param value The value to assign to the property. Can be any serializable value.
-   * @param customKey Optional custom key for accessing state in a specific storage location.
-   *                  Useful for multi-tenant scenarios or when state needs to be partitioned.
-   *
-   * @returns A promise that resolves when the set operation is complete
-   *
    * @example Basic usage
    * ```typescript
    * const counterProperty = userState.createProperty<number>("counter");
@@ -394,6 +415,7 @@ export class AgentStatePropertyAccessor<T = any> implements StatePropertyAccesso
    * await dataProperty.set(context, updatedData, tenantKey);
    * await userState.saveChanges(context);
    * ```
+   *
    */
   async set (context: TurnContext, value: T, customKey?: CustomKey): Promise<void> {
     const obj: any = await this.state.load(context, false, customKey)

package/src/storage/fileStorage.ts

@@ -8,7 +8,7 @@ import fs from 'fs'
 import { Storage, StoreItem } from './storage'
 
 /**
- * @summary A file-based storage implementation that persists data to the local filesystem.
+ * A file-based storage implementation that persists data to the local filesystem.
  *
  * @remarks
  * FileStorage stores all data in a single JSON file named 'state.json' within a specified folder.
@@ -47,7 +47,6 @@ import { Storage, StoreItem } from './storage'
  * await storage.delete(['conversation456']);
  * ```
  *
-
  */
 export class FileStorage implements Storage {
   private _folder: string
@@ -57,6 +56,7 @@ export class FileStorage implements Storage {
    * Creates a new FileStorage instance that stores data in the specified folder.
    *
    * @param folder The absolute or relative path to the folder where the state.json file will be stored
+   * @throws May throw filesystem errors if the folder cannot be created or accessed
    *
    * @remarks
    * The constructor performs the following initialization steps:
@@ -64,7 +64,6 @@ export class FileStorage implements Storage {
    * 2. Creates an empty state.json file if it doesn't exist
    * 3. Loads existing data from state.json into memory for fast access
    *
-   * @throws May throw filesystem errors if the folder cannot be created or accessed
    */
   constructor (folder: string) {
     this._folder = folder
@@ -83,13 +82,13 @@ export class FileStorage implements Storage {
    *
    * @param keys Array of keys to read from storage
    * @returns Promise resolving to an object containing the requested items (keys that don't exist are omitted)
-   *
    * @throws ReferenceError if keys array is empty or undefined
    *
    * @remarks
    * This method reads from the in-memory cache that was loaded during construction,
    * making it very fast but potentially returning stale data if the file was
    * modified by external processes.
+   *
    */
   read (keys: string[]) : Promise<StoreItem> {
     return new Promise((resolve, reject) => {
@@ -119,8 +118,10 @@ export class FileStorage implements Storage {
    * to the state.json file. The file is written with pretty-printing (2-space indentation)
    * for better readability during development and debugging.
    *
-   * Note: This implementation does not support eTag-based optimistic concurrency control.
-   * Any eTag values in the changes object are ignored.
+   * > [!NOTE]
+   * > This implementation does not support eTag-based optimistic concurrency control.
+   * > Any eTag values in the changes object are ignored.
+   *
    */
   write (changes: StoreItem) : Promise<void> {
     const keys = Object.keys(changes)
@@ -143,6 +144,7 @@ export class FileStorage implements Storage {
    * This method removes the specified keys from both the in-memory cache
    * and writes the updated state to the state.json file. Keys that don't
    * exist in storage are silently ignored.
+   *
    */
   delete (keys: string[]) : Promise<void> {
     return new Promise((resolve, reject) => {

package/src/storage/memoryStorage.ts

@@ -39,10 +39,12 @@ export class MemoryStorage implements Storage {
   /**
    * Gets a single shared instance of the MemoryStorage class.
    *
+   * @returns The singleton instance of MemoryStorage
+   *
+   * @remarks
    * Using this method ensures that the same storage instance is used across
    * the application, allowing for shared state without passing references.
    *
-   * @returns The singleton instance of MemoryStorage
    */
   static getSingleInstance (): MemoryStorage {
     if (!MemoryStorage.instance) {
@@ -78,14 +80,15 @@ export class MemoryStorage implements Storage {
   /**
    * Writes storage items to memory.
    *
+   * @param changes The items to write, indexed by key
+   * @returns A promise that resolves when the write operation is complete
+   * @throws Will throw an error if changes are not provided or if there's an eTag conflict
+   *
+   * @remarks
    * This method supports optimistic concurrency control through eTags.
    * If an item has an eTag, it will only be updated if the existing item
    * has the same eTag. If an item has an eTag of '*' or no eTag, it will
    * always be written regardless of the current state.
-   *
-   * @param changes The items to write, indexed by key
-   * @returns A promise that resolves when the write operation is complete
-   * @throws Will throw an error if changes are not provided or if there's an eTag conflict
    */
   async write (changes: StoreItem): Promise<void> {
     if (!changes || changes.length === 0) {
@@ -124,13 +127,15 @@ export class MemoryStorage implements Storage {
   /**
    * Saves an item to memory with a new eTag.
    *
+   * @param key The key of the item to save
+   * @param item The item to save
+   *
+   * @remarks
    * This private method handles the details of:
    * - Creating a clone of the item to prevent modification of the original
    * - Generating a new eTag for optimistic concurrency control
    * - Converting the item to a JSON string for storage
    *
-   * @param key The key of the item to save
-   * @param item The item to save
    * @private
    */
   private saveItem (key: string, item: unknown): void {

package/src/storage/storage.ts

@@ -7,41 +7,58 @@ import { TurnContext } from '../turnContext'
 
 /**
  * Represents an item to be stored in a storage provider.
+ *
+ * @remarks
  * Each item can contain arbitrary data along with an optional eTag for optimistic concurrency control.
  */
 export interface StoreItem {
   /**
    * Optional eTag used for optimistic concurrency control.
+   *
+   * @remarks
    * When set to '*', it indicates that the write should proceed regardless of existing data.
    * When comparing eTags, exact string matching is used to determine if data has changed.
+   *
    */
   eTag?: string;
 
   /**
    * Additional properties can be stored in the item.
+   *
+   * @remarks
    * Each storage provider may have specific requirements or limitations on property names and values.
+   *
    */
   [key: string]: any;
 }
 
 /**
  * Represents a collection of store items indexed by key.
+ *
+ * @remarks
  * Used as the return type for storage read operations.
+ *
  */
 export interface StoreItems {
   /**
    * Keys are the storage item identifiers, and values are the stored items.
+   *
+   * @remarks
    * If a requested key is not found during a read operation, it will not appear in this collection.
+   *
    */
   [key: string]: any;
 }
 
 /**
  * A factory function to generate storage keys based on the conversation context.
- * Allows different storage strategies based on the conversation state.
  *
  * @param context The TurnContext for the current turn of conversation
  * @returns A string key for storage that uniquely identifies where to store the data
+ *
+ * @remarks
+ * Allows different storage strategies based on the conversation state.
+ *
  */
 export type StorageKeyFactory = (context: TurnContext) => string | Promise<string>