@microsoft/agents-hosting 1.0.0 → 1.0.3-g444d99f704

package/dist/src/auth/jwt-middleware.js

@@ -66,28 +66,36 @@ const authorizeJWT = (authConfig) => {
     return async function (req, res, next) {
         let failed = false;
         logger.debug('authorizing jwt');
-        const authHeader = req.headers.authorization;
-        if (authHeader) {
-            const token = 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) {
-                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;
+            if (authHeader) {
+                const token = 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) {
+                    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/dist/src/auth/jwt-middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"jwt-middleware.js","sourceRoot":"","sources":["../../../src/auth/jwt-middleware.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jwt-middleware.js","sourceRoot":"","sources":["../../../src/auth/jwt-middleware.ts"],"names":[],"mappings":"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"}

package/dist/src/cards/adaptiveCard.d.ts

@@ -10,7 +10,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/dist/src/headerPropagation.d.ts

@@ -36,36 +36,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/dist/src/state/agentState.d.ts

@@ -7,6 +7,8 @@ import { TurnContext } from '../turnContext';
 import { AgentStatePropertyAccessor } from './agentStatePropertyAccesor';
 /**
  * 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 {
@@ -23,6 +25,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.
  */
@@ -37,7 +41,8 @@ export interface CustomKey {
     conversationId: string;
 }
 /**
- * @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,
@@ -57,30 +62,36 @@ export declare class AgentState {
     constructor(storage: Storage, storageKey: StorageKeyFactory);
     /**
      * 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>;
     /**
      * 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.
      */
     load(context: TurnContext, force?: boolean, customKey?: CustomKey): Promise<any>;
     /**
      * 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.
      */
     saveChanges(context: TurnContext, force?: boolean, customKey?: CustomKey): Promise<void>;
     /**
@@ -94,11 +105,14 @@ export declare class AgentState {
     private getStorageOrCustomKey;
     /**
      * 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.
+     *
      */
     clear(context: TurnContext): Promise<void>;
     /**
@@ -118,10 +132,12 @@ export declare class AgentState {
     get(context: TurnContext): any | undefined;
     /**
      * 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;

package/dist/src/state/agentState.js

@@ -10,7 +10,8 @@ const agentStatePropertyAccesor_1 = require("./agentStatePropertyAccesor");
 const logger_1 = require("@microsoft/agents-activity/logger");
 const logger = (0, logger_1.debug)('agents:state');
 /**
- * @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,
@@ -30,10 +31,12 @@ class AgentState {
         this.stateKey = Symbol('state');
         /**
          * 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
          */
         this.calculateChangeHash = (item) => {
@@ -47,10 +50,12 @@ 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(name) {
         const prop = new agentStatePropertyAccesor_1.AgentStatePropertyAccessor(this, name);
@@ -58,12 +63,14 @@ 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.
      */
     async load(context, force = false, customKey) {
         const cached = context.turnState.get(this.stateKey);
@@ -80,12 +87,14 @@ 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.
      */
     async saveChanges(context, force = false, customKey) {
         let cached = context.turnState.get(this.stateKey);
@@ -124,11 +133,14 @@ 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.
+     *
      */
     async clear(context) {
         const emptyObjectToForceSave = { state: {}, hash: '' };

package/dist/src/state/agentState.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentState.js","sourceRoot":"","sources":["../../../src/state/agentState.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agentState.js","sourceRoot":"","sources":["../../../src/state/agentState.ts"],"names":[],"mappings":"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"}

package/dist/src/state/agentStatePropertyAccesor.d.ts

@@ -7,28 +7,35 @@ 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.
      *
@@ -36,10 +43,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>;
     /**
@@ -52,25 +60,30 @@ 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:
  *
@@ -82,6 +95,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
@@ -172,8 +190,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
  */
@@ -183,13 +199,13 @@ export declare class AgentStatePropertyAccessor<T = any> implements StatePropert
     /**
      * 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
@@ -198,10 +214,17 @@ export declare class AgentStatePropertyAccessor<T = any> implements StatePropert
      * // Direct construction (not recommended)
      * const accessor = new AgentStatePropertyAccessor<UserProfile>(userState, "userProfile");
      * ```
+     *
      */
     constructor(state: AgentState, 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
@@ -211,13 +234,7 @@ export declare class AgentStatePropertyAccessor<T = any> implements StatePropert
      * - 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");
      *
@@ -237,10 +254,20 @@ export declare class AgentStatePropertyAccessor<T = any> implements StatePropert
      * await userSettings.delete(context, tenantKey);
      * await userState.saveChanges(context);
      * ```
+     *
      */
     delete(context: TurnContext, customKey?: CustomKey): Promise<void>;
     /**
-     * @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
@@ -257,14 +284,6 @@ export declare class AgentStatePropertyAccessor<T = any> implements StatePropert
      * **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");
@@ -303,10 +322,19 @@ export declare class AgentStatePropertyAccessor<T = any> implements StatePropert
      * const tenantKey = { key: `tenant_${tenantId}` };
      * const tenantData = await dataProperty.get(context, defaultData, tenantKey);
      * ```
+     *
      */
     get(context: TurnContext, defaultValue?: T, customKey?: CustomKey): Promise<T>;
     /**
-     * @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
@@ -323,13 +351,6 @@ export declare class AgentStatePropertyAccessor<T = any> implements StatePropert
      * **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");
@@ -371,6 +392,7 @@ export declare class AgentStatePropertyAccessor<T = any> implements StatePropert
      * await dataProperty.set(context, updatedData, tenantKey);
      * await userState.saveChanges(context);
      * ```
+     *
      */
     set(context: TurnContext, value: T, customKey?: CustomKey): Promise<void>;
 }