@microsoft/agents-hosting/dist/src/oauth/oAuthFlow.d.ts

Microsoft 365 Agents SDK for JavaScript

import { Activity } from '@microsoft/agents-activity';
import { TurnContext, Storage } from '../';
import { UserTokenClient } from './userTokenClient';
import { TokenResponse } from './userTokenClient.types';
/**
 * Represents the state of the OAuth flow.
 * @interface FlowState
 */
export interface FlowState {
    /** Indicates whether the OAuth flow has been started */
    flowStarted: boolean | undefined;
    /** Timestamp when the OAuth flow expires (in milliseconds since epoch) */
    flowExpires: number | undefined;
    /** The absolute OAuth connection name used for the flow, null if not set */
    absOauthConnectionName: string;
    /** Optional activity to continue the flow with, used for multi-turn scenarios */
    continuationActivity?: Activity | null;
    eTag?: string;
}
/**
 * Manages the OAuth flow
 */
export declare class OAuthFlow {
    private storage;
    /**
     * The user token client used for managing user tokens.
     */
    userTokenClient: UserTokenClient;
    /**
     * The current state of the OAuth flow.
     */
    state: FlowState;
    /**
     * The ID of the token exchange request, used to deduplicate requests.
     */
    tokenExchangeId: string | null;
    /**
     * In-memory cache for tokens with expiration.
     */
    private tokenCache;
    /**
     * The name of the OAuth connection.
     */
    absOauthConnectionName: string;
    /**
     * The title of the OAuth card.
     */
    cardTitle: string;
    /**
     * The text of the OAuth card.
     */
    cardText: string;
    /**
     * Creates a new instance of OAuthFlow.
     * @param storage The storage provider for persisting flow state.
     * @param absOauthConnectionName The absolute OAuth connection name.
     * @param tokenClient Optional user token client. If not provided, will be initialized automatically.
     * @param cardTitle Optional title for the OAuth card. Defaults to 'Sign in'.
     * @param cardText Optional text for the OAuth card. Defaults to 'login'.
     */
    constructor(storage: Storage, absOauthConnectionName: string, tokenClient: UserTokenClient, cardTitle?: string, cardText?: string);
    /**
     * Retrieves the user token from the user token service with in-memory caching for 10 minutes.
     * @param context The turn context containing the activity information.
     * @returns A promise that resolves to the user token response.
     * @throws Will throw an error if the channelId or from properties are not set in the activity.
     */
    getUserToken(context: TurnContext): Promise<TokenResponse>;
    /**
     * Begins the OAuth flow.
     * @param context The turn context.
     * @returns A promise that resolves to the user token if available, or undefined if OAuth flow needs to be started.
     */
    beginFlow(context: TurnContext): Promise<TokenResponse | undefined>;
    /**
     * Continues the OAuth flow.
     * @param context The turn context.
     * @returns A promise that resolves to the user token response.
     */
    continueFlow(context: TurnContext): Promise<TokenResponse>;
    /**
     * Signs the user out.
     * @param context The turn context.
     * @returns A promise that resolves when the sign-out operation is complete.
     */
    signOut(context: TurnContext): Promise<void>;
    /**
     * Gets the user state for the OAuth flow.
     * @param context The turn context.
     * @returns A promise that resolves to the flow state.
     */
    getFlowState(context: TurnContext): Promise<FlowState>;
    /**
     * Sets the flow state for the OAuth flow.
     * @param context The turn context.
     * @param flowState The flow state to set.
     * @returns A promise that resolves when the flow state is set.
     */
    setFlowState(context: TurnContext, flowState: FlowState): Promise<void>;
    /**
     * Initializes the user token client if not already initialized.
     * @param context The turn context used to get authentication credentials.
     */
    private refreshToken;
    /**
     * Generates a cache key for storing user tokens.
     * @param context The turn context containing activity information.
     * @returns The cache key string in format: channelId_userId_connectionName.
     * @throws Will throw an error if required activity properties are missing.
     */
    private getCacheKey;
    /**
     * Generates a storage key for persisting OAuth flow state.
     * @param context The turn context containing activity information.
     * @returns The storage key string in format: oauth/channelId/conversationId/userId/flowState.
     * @throws Will throw an error if required activity properties are missing.
     */
    private getFlowStateKey;
}