@microsoft/teams-ai/lib/TurnState.d.ts

SDK focused on building AI based applications for Microsoft Teams.

/**
 * @module teams-ai
 */
/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */
import { TurnContext, Storage } from 'botbuilder';
import { Memory } from './MemoryFork';
import { InputFile } from './InputFileDownloader';
/**
 * Default conversation state
 * @remarks
 * Inherit a new interface from this base interface to strongly type the applications conversation
 * state.
 */
export interface DefaultConversationState {
}
/**
 * Default user state
 * @remarks
 * Inherit a new interface from this base interface to strongly type the applications user
 * state.
 */
export interface DefaultUserState {
}
/**
 * Default temp state
 * @remarks
 * Inherit a new interface from this base interface to strongly type the applications temp
 * state.
 */
export interface DefaultTempState {
    /**
     * Input passed from the user to the AI Library
     */
    input: string;
    /**
     * Downloaded files passed by the user to the AI Library
     */
    inputFiles: InputFile[];
    /**
     * Output returned from the last executed action
     */
    lastOutput: string;
    /**
     * All outputs returned from the action sequence that was executed
     */
    actionOutputs: Record<string, string>;
    /**
     * User authentication tokens
     */
    authTokens: {
        [key: string]: string;
    };
    /**
     * Flag indicating whether a token exchange event has already been processed
     */
    duplicateTokenExchange?: boolean;
}
/**
 * Base class defining a collection of turn state scopes.
 * @remarks
 * Developers can create a derived class that extends `TurnState` to add additional state scopes.
 * ```JavaScript
 * class MyTurnState extends TurnState {
 *   protected async onComputeStorageKeys(context) {
 *     const keys = await super.onComputeStorageKeys(context);
 *     keys['myScope'] = `myScopeKey`;
 *     return keys;
 *   }
 *
 *   public get myScope() {
 *     const scope = this.getScope('myScope');
 *     if (!scope) {
 *       throw new Error(`MyTurnState hasn't been loaded. Call load() first.`);
 *     }
 *     return scope.value;
 *   }
 *
 *   public set myScope(value) {
 *     const scope = this.getScope('myScope');
 *     if (!scope) {
 *       throw new Error(`MyTurnState hasn't been loaded. Call load() first.`);
 *     }
 *     scope.replace(value);
 *   }
 * }
 * ```
 */
/**
 * Represents the turn state for a conversation.
 * Turn state includes conversation state, user state, and temporary state.
 * Provides methods to access, modify, and delete the state objects.
 * @template TConversationState
 * @param {TConversationState} TConversationState The type of the conversation state object.
 * @param {TUserState} TUserState The type of the user state object.
 * @param {TTempState} TTempState - The type of the temporary state object.
 */
export declare class TurnState<TConversationState = DefaultConversationState, TUserState = DefaultUserState, TTempState = DefaultTempState> implements Memory {
    private _scopes;
    private _isLoaded;
    private _loadingPromise?;
    private _stateNotLoadedString;
    /**
     * Accessor for the conversation state.
     */
    /**
     * Gets the conversation state from the turn state.
     * @template TConversationState
     * @returns {TConversationState} The conversation state.
     * @throws Error if TurnState hasn't been loaded. Call load() first.
     */
    get conversation(): TConversationState;
    /**
     * Replaces the conversation state with a new value.
     * @param {TConversationState} value New value to replace the conversation state with.
     */
    set conversation(value: TConversationState);
    /**
     * Gets a value indicating whether the applications turn state has been loaded.
     * @returns {boolean} True if the applications turn state has been loaded, false otherwise.
     */
    get isLoaded(): boolean;
    /**
     * Accessor for the temp state.
     @returns {TTempState} The temp TurnState.
     @throws Error if TurnState hasn't been loaded. Call load() first.
     */
    get temp(): TTempState;
    /**
     * Replaces the temp state with a new value.
     * @param {TTempState} value New value to replace the temp state with.
     * @throws Error if TurnState hasn't been loaded. Call load() first.
     */
    set temp(value: TTempState);
    /**
     * Accessor for the user state.
     * @returns {TUserState} The user TurnState.
     */
    get user(): TUserState;
    /**
     * Replaces the user state with a new value.
     */
    set user(value: TUserState);
    /**
     * Deletes the state object for the current conversation from storage.
     */
    deleteConversationState(): void;
    /**
     * Deletes the temp state object.
     */
    deleteTempState(): void;
    /**
     * Deletes the state object for the current user from storage.
     */
    deleteUserState(): void;
    /**
     * Gets a state scope by name.
     * @param {string} scope Name of the state scope to return. (i.e. 'conversation', 'user', or 'temp')
     * @returns {string | undefined} The state scope or undefined if not found.
     */
    getScope(scope: string): TurnStateEntry | undefined;
    /**
     * Deletes a value from the memory.
     * @param {string} path Path to the value to delete in the form of `[scope].property`. If scope is omitted, the value is deleted from the temporary scope.
     */
    deleteValue(path: string): void;
    /**
     * Checks if a value exists in the memory.
     * @param {string} path Path to the value to check in the form of `[scope].property`. If scope is omitted, the value is checked in the temporary scope.
     * @returns {boolean} True if the value exists, false otherwise.
     */
    hasValue(path: string): boolean;
    /**
     * Retrieves a value from the memory.
     * @template TValue
     * @param {TValue} path Path to the value to retrieve in the form of `[scope].property`. If scope is omitted, the value is retrieved from the temporary scope.
     * @returns {string} The value or undefined if not found.
     */
    getValue<TValue = unknown>(path: string): TValue;
    /**
     * Assigns a value to the memory.
     * @param {string} path Path to the value to assign in the form of `[scope].property`. If scope is omitted, the value is assigned to the temporary scope.
     * @param {unknown} value Value to assign.
     */
    setValue(path: string, value: unknown): void;
    /**
     * Loads all of the state scopes for the current turn.
     * @param {TurnContext} context Context for the current turn of conversation with the user.
     * @param {Storage} storage Optional. Storage provider to load state scopes from.
     * @returns {boolean} True if the states needed to be loaded.
     */
    load(context: TurnContext, storage?: Storage): Promise<boolean>;
    /**
     * Saves all of the state scopes for the current turn.
     * @param {TurnContext} context Context for the current turn of conversation with the user.
     * @param {Storage} storage Optional. Storage provider to save state scopes to.
     */
    save(context: TurnContext, storage?: Storage): Promise<void>;
    /**
     * Computes the storage keys for the state scopes being persisted.
     * @remarks
     * Can be overridden in derived classes to add additional storage scopes.
     * @param {TurnContext} context Context for the current turn of conversation with the user.
     * @returns {Promise<Record<string, string>>} A dictionary of scope names -> storage keys.
     * @throws Error if the context is missing a required property.
     */
    protected onComputeStorageKeys(context: TurnContext): Promise<Record<string, string>>;
    /**
     * @private
     * @param {string} path Path to the value to check in the form of `[scope].property`. If scope is omitted, the value is checked in the temporary scope.
     * @returns {{ scope: TurnStateEntry; name: string }} Scope and name.
     */
    private getScopeAndName;
}
/**
 * Accessor class for managing an individual state scope.
 */
export declare class TurnStateEntry {
    private _value;
    private _storageKey?;
    private _deleted;
    private _hash;
    /**
     * Creates a new instance of the `TurnStateEntry` class.
     * @param {Record<string, unknown>} value Optional. Value to initialize the state scope with. The default is an {} object.
     * @param {string} storageKey Optional. Storage key to use when persisting the state scope.
     */
    constructor(value?: Record<string, unknown>, storageKey?: string);
    /**
     * Gets a value indicating whether the state scope has changed since it was last loaded.
     * @returns {boolean} A value indicating whether the state scope has changed.
     */
    get hasChanged(): boolean;
    /**
     * Gets a value indicating whether the state scope has been deleted.
     * @returns {boolean} A value indicating whether the state scope has been deleted.
     */
    get isDeleted(): boolean;
    /**
     * Gets the value of the state scope.
     * @returns {Record<string, unknown>} value of the state scope.
     */
    get value(): Record<string, unknown>;
    /**
     * Gets the storage key used to persist the state scope.
     * @returns {string | undefined} The storage key used to persist the state scope.
     */
    get storageKey(): string | undefined;
    /**
     * Clears the state scope.
     */
    delete(): void;
    /**
     * Replaces the state scope with a new value.
     * @template TValue
     * @param {TValue} value New value to replace the state scope with.
     */
    replace(value?: Record<string, unknown>): void;
}
//# sourceMappingURL=TurnState.d.ts.map