@microsoft/agents-hosting 0.2.14 → 0.4.1

package/dist/src/app/inputFileDownloader.d.ts

@@ -4,11 +4,33 @@
  */
 import { TurnContext } from '../turnContext';
 import { TurnState } from './turnState';
+/**
+ * Represents a file input with its content, type, and optional URL.
+ */
 export interface InputFile {
+    /**
+     * The content of the file as a Buffer.
+     */
     content: Buffer;
+    /**
+     * The MIME type of the file content.
+     */
     contentType: string;
+    /**
+     * An optional URL pointing to the file content.
+     */
     contentUrl?: string;
 }
+/**
+ * Interface for downloading input files in a specific turn context and state.
+ */
 export interface InputFileDownloader<TState extends TurnState = TurnState> {
+    /**
+     * Downloads files based on the provided turn context and state.
+     *
+     * @param context - The turn context for the current operation.
+     * @param state - The state associated with the current turn.
+     * @returns A promise that resolves to an array of input files.
+     */
     downloadFiles(context: TurnContext, state: TState): Promise<InputFile[]>;
 }

package/dist/src/app/oauth/authorization.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { TurnContext } from '../../turnContext';
+import { TurnState } from '../turnState';
+import { Storage } from '../../storage';
+import { OAuthFlow, TokenResponse } from '../../oauth';
+/**
+ * Interface defining an authorization handler for OAuth flows
+ * @interface AuthHandler
+ */
+export interface AuthHandler {
+    /** Connection name for the auth provider */
+    name?: string;
+    /** Whether authorization should be triggered automatically */
+    auto?: boolean;
+    /** The OAuth flow implementation */
+    flow?: OAuthFlow;
+    /** Title to display on auth cards/UI */
+    title?: string;
+    /** Text to display on auth cards/UI */
+    text?: string;
+}
+/**
+ * Options for configuring user authorization.
+ * Contains settings to configure OAuth connections.
+ */
+export interface AuthorizationHandlers extends Record<string, AuthHandler> {
+}
+/**
+ * Class responsible for managing authorization and OAuth flows
+ * @class Authorization
+ */
+export declare class Authorization {
+    _authHandlers: AuthorizationHandlers;
+    /**
+     * Creates a new instance of UserAuthorization.
+     * @param {Storage} storage - The storage system to use for state management.
+     * @param {AuthorizationHandlers} authHandlers - Configuration for OAuth providers
+     * @throws {Error} If storage is null/undefined or no auth handlers are provided
+     */
+    constructor(storage: Storage, authHandlers: AuthorizationHandlers);
+    /**
+     * Gets the token for a specific auth handler
+     * @param {TurnContext} context - The context object for the current turn
+     * @param {string} [authHandlerId] - Optional ID of the auth handler to use, defaults to first handler
+     * @returns {Promise<TokenResponse>} The token response from the OAuth provider
+     */
+    getToken(context: TurnContext, authHandlerId?: string): Promise<TokenResponse>;
+    /**
+     * Begins or continues an OAuth flow
+     * @param {TurnContext} context - The context object for the current turn
+     * @param {TurnState} state - The state object for the current turn
+     * @param {string} [authHandlerId] - Optional ID of the auth handler to use, defaults to first handler
+     * @returns {Promise<TokenResponse>} The token response from the OAuth provider
+     */
+    beginOrContinueFlow(context: TurnContext, state: TurnState, authHandlerId?: string): Promise<TokenResponse>;
+    /**
+     * Gets the current state of the OAuth flow
+     * @param {string} [authHandlerId] - Optional ID of the auth handler to check, defaults to first handler
+     * @returns {boolean} Whether the flow has started
+     */
+    getFlowState(authHandlerId?: string): boolean;
+    /**
+     * Resolves the auth handler to use based on the provided ID
+     * @param {string} [authHandlerId] - Optional ID of the auth handler to resolve, defaults to first handler
+     * @returns {AuthHandler} The resolved auth handler
+     */
+    resolverHandler: (authHandlerId?: string) => AuthHandler;
+    /**
+     * Signs out the current user.
+     * This method clears the user's token and resets the SSO state.
+     *
+     * @param {TurnContext} context - The context object for the current turn.
+     * @param {TurnState} state - The state object for the current turn.
+     * @param {string} [authHandlerId] - Optional ID of the auth handler to use for sign out
+     * @returns {Promise<void>}
+     */
+    signOut(context: TurnContext, state: TurnState, authHandlerId?: string): Promise<void>;
+    _signInHandler: ((context: TurnContext, state: TurnState, authHandlerId?: string) => void) | null;
+    /**
+     * Sets a handler to be called when sign-in is successfully completed
+     * @param {Function} handler - The handler function to call on successful sign-in
+     */
+    onSignInSuccess(handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => void): void;
+}

package/dist/src/app/oauth/authorization.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Authorization = void 0;
+const logger_1 = require("../../logger");
+const oauth_1 = require("../../oauth");
+const state_1 = require("../../state");
+const logger = (0, logger_1.debug)('agents:authorization');
+/**
+ * Class responsible for managing authorization and OAuth flows
+ * @class Authorization
+ */
+class Authorization {
+    /**
+     * Creates a new instance of UserAuthorization.
+     * @param {Storage} storage - The storage system to use for state management.
+     * @param {AuthorizationHandlers} authHandlers - Configuration for OAuth providers
+     * @throws {Error} If storage is null/undefined or no auth handlers are provided
+     */
+    constructor(storage, authHandlers) {
+        var _a, _b, _c, _d;
+        /**
+         * Resolves the auth handler to use based on the provided ID
+         * @param {string} [authHandlerId] - Optional ID of the auth handler to resolve, defaults to first handler
+         * @returns {AuthHandler} The resolved auth handler
+         */
+        this.resolverHandler = (authHandlerId) => {
+            if (authHandlerId) {
+                return this._authHandlers[authHandlerId];
+            }
+            return this._authHandlers[Object.keys(this._authHandlers)[0]];
+        };
+        this._signInHandler = null;
+        if (storage === undefined || storage === null) {
+            throw new Error('Storage is required for UserAuthorization');
+        }
+        const userState = new state_1.UserState(storage);
+        if (authHandlers === undefined || Object.keys(authHandlers).length === 0) {
+            throw new Error('The authorization does not have any auth handlers');
+        }
+        this._authHandlers = authHandlers;
+        for (const ah in this._authHandlers) {
+            if (this._authHandlers[ah].name === undefined && process.env[ah + '_connectionName'] === undefined) {
+                throw new Error(`AuthHandler name ${ah}_connectionName not set in autorization and not found in env vars.`);
+            }
+            const currentAuthHandler = this._authHandlers[ah];
+            currentAuthHandler.name = (_a = currentAuthHandler.name) !== null && _a !== void 0 ? _a : process.env[ah + '_connectionName'];
+            currentAuthHandler.title = (_b = currentAuthHandler.title) !== null && _b !== void 0 ? _b : process.env[ah + '_connectionTitle'];
+            currentAuthHandler.text = (_c = currentAuthHandler.text) !== null && _c !== void 0 ? _c : process.env[ah + '_connectionText'];
+            currentAuthHandler.auto = (_d = currentAuthHandler.auto) !== null && _d !== void 0 ? _d : process.env[ah + '_connectionAuto'] === 'true';
+            currentAuthHandler.flow = new oauth_1.OAuthFlow(userState, currentAuthHandler.name, null, currentAuthHandler.title, currentAuthHandler.text);
+        }
+        logger.info('Authorization handlers configured with', this._authHandlers.length, 'handlers');
+    }
+    /**
+     * Gets the token for a specific auth handler
+     * @param {TurnContext} context - The context object for the current turn
+     * @param {string} [authHandlerId] - Optional ID of the auth handler to use, defaults to first handler
+     * @returns {Promise<TokenResponse>} The token response from the OAuth provider
+     */
+    async getToken(context, authHandlerId) {
+        var _a;
+        logger.info('getToken from user token service for authHandlerId:', authHandlerId);
+        const authHandler = this.resolverHandler(authHandlerId);
+        return await ((_a = authHandler.flow) === null || _a === void 0 ? void 0 : _a.getUserToken(context));
+    }
+    /**
+     * Begins or continues an OAuth flow
+     * @param {TurnContext} context - The context object for the current turn
+     * @param {TurnState} state - The state object for the current turn
+     * @param {string} [authHandlerId] - Optional ID of the auth handler to use, defaults to first handler
+     * @returns {Promise<TokenResponse>} The token response from the OAuth provider
+     */
+    async beginOrContinueFlow(context, state, authHandlerId) {
+        logger.info('beginOrContinueFlow for authHandlerId:', authHandlerId);
+        const flow = this.resolverHandler(authHandlerId).flow;
+        let tokenResponse;
+        if (flow.state.flowStarted === false) {
+            tokenResponse = await flow.beginFlow(context);
+        }
+        else {
+            tokenResponse = await flow.continueFlow(context);
+            if (tokenResponse.status === oauth_1.TokenRequestStatus.Success) {
+                if (this._signInHandler) {
+                    await this._signInHandler(context, state, authHandlerId);
+                }
+            }
+        }
+        return tokenResponse;
+    }
+    /**
+     * Gets the current state of the OAuth flow
+     * @param {string} [authHandlerId] - Optional ID of the auth handler to check, defaults to first handler
+     * @returns {boolean} Whether the flow has started
+     */
+    getFlowState(authHandlerId) {
+        var _a;
+        const flow = this.resolverHandler(authHandlerId).flow;
+        return (_a = flow.state) === null || _a === void 0 ? void 0 : _a.flowStarted;
+    }
+    /**
+     * Signs out the current user.
+     * This method clears the user's token and resets the SSO state.
+     *
+     * @param {TurnContext} context - The context object for the current turn.
+     * @param {TurnState} state - The state object for the current turn.
+     * @param {string} [authHandlerId] - Optional ID of the auth handler to use for sign out
+     * @returns {Promise<void>}
+     */
+    async signOut(context, state, authHandlerId) {
+        var _a;
+        logger.info('signOut for authHandlerId:', authHandlerId);
+        if (authHandlerId === undefined) { // aw
+            for (const ah in this._authHandlers) {
+                const flow = this._authHandlers[ah].flow;
+                await (flow === null || flow === void 0 ? void 0 : flow.signOut(context));
+            }
+        }
+        else {
+            await ((_a = this.resolverHandler(authHandlerId).flow) === null || _a === void 0 ? void 0 : _a.signOut(context));
+        }
+    }
+    /**
+     * Sets a handler to be called when sign-in is successfully completed
+     * @param {Function} handler - The handler function to call on successful sign-in
+     */
+    onSignInSuccess(handler) {
+        this._signInHandler = handler;
+    }
+}
+exports.Authorization = Authorization;
+//# sourceMappingURL=authorization.js.map

package/dist/src/app/oauth/authorization.js.map

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

package/dist/src/app/routeHandler.d.ts

@@ -4,4 +4,12 @@
  */
 import { TurnContext } from '../turnContext';
 import { TurnState } from './turnState';
+/**
+ * A handler function for routing operations in a specific turn context and state.
+ *
+ * @typeParam TState - The type of the turn state.
+ * @param context - The turn context for the current operation.
+ * @param state - The state associated with the current turn.
+ * @returns A promise that resolves when the routing operation is complete.
+ */
 export type RouteHandler<TState extends TurnState> = (context: TurnContext, state: TState) => Promise<void>;

package/dist/src/app/routeSelector.d.ts

@@ -3,5 +3,14 @@
  * Licensed under the MIT License.
  */
 import { TurnContext } from '../turnContext';
+/**
+ * A function that determines whether a specific condition is met in the given turn context.
+ *
+ * @param context - The turn context for the current operation.
+ * @returns A promise that resolves to a boolean indicating whether the condition is met.
+ */
 export type Selector = (context: TurnContext) => Promise<boolean>;
+/**
+ * A specialized selector for routing operations.
+ */
 export type RouteSelector = Selector;

package/dist/src/app/turnState.d.ts

@@ -7,24 +7,25 @@ import { AppMemory } from './appMemory';
 import { InputFile } from './inputFileDownloader';
 import { TurnStateEntry } from './turnStateEntry';
 import { TurnContext } from '../turnContext';
+/**
+ * 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 {
-    input: string;
+    /** Collection of files attached to the current message */
     inputFiles: InputFile[];
-    lastOutput: string;
-    actionOutputs: Record<string, string>;
-    authTokens: {
-        [key: string]: string;
-    };
-    duplicateTokenExchange?: boolean;
-}
-export interface DefaultSSOState {
-    flowStarted: boolean;
-    userToken: string;
-    flowExpires: number;
 }
 /**
  * Base class defining a collection of turn state scopes.
@@ -55,31 +56,143 @@ 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 declare class TurnState<TConversationState = DefaultConversationState, TUserState = DefaultUserState, TTempState = DefaultTempState, TSSOState = DefaultSSOState> implements AppMemory {
+export declare class TurnState<TConversationState = DefaultConversationState, TUserState = DefaultUserState, TTempState = DefaultTempState> implements AppMemory {
     private _scopes;
     private _isLoaded;
     private _loadingPromise?;
     private _stateNotLoadedString;
+    /**
+     * 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
+     */
     get conversation(): TConversationState;
+    /**
+     * Sets the conversation-scoped state.
+     * @param value - The new conversation state object
+     * @throws Error if state hasn't been loaded
+     */
     set conversation(value: TConversationState);
+    /**
+     * Gets whether the state has been loaded from storage
+     * @returns True if the state has been loaded, false otherwise
+     */
     get isLoaded(): boolean;
+    /**
+     * 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
+     */
     get temp(): TTempState;
+    /**
+     * Sets the temporary state for the current turn.
+     * @param value - The new temporary state object
+     * @throws Error if state hasn't been loaded
+     */
     set temp(value: TTempState);
+    /**
+     * 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
+     */
     get user(): TUserState;
+    /**
+     * Sets the user-scoped state.
+     * @param value - The new user state object
+     * @throws Error if state hasn't been loaded
+     */
     set user(value: TUserState);
-    get sso(): TSSOState;
-    set sso(value: TSSOState);
+    /**
+     * 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
+     */
     deleteConversationState(): void;
+    /**
+     * 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
+     */
     deleteTempState(): void;
+    /**
+     * 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
+     */
     deleteUserState(): void;
+    /**
+     * 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
+     */
     getScope(scope: string): TurnStateEntry | undefined;
+    /**
+     * 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
+     */
     deleteValue(path: string): void;
+    /**
+     * 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
+     */
     hasValue(path: string): boolean;
+    /**
+     * 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
+     */
     getValue<TValue = unknown>(path: string): 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
+     */
     setValue(path: string, value: unknown): void;
+    /**
+     * 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
+     */
     load(context: TurnContext, storage?: Storage, force?: boolean): Promise<boolean>;
+    /**
+     * 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
+     */
     save(context: TurnContext, storage?: Storage): Promise<void>;
+    /**
+     * 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>>;
+    /**
+     * 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;
 }