[JS] feat: add jsdoc for authentication code (#850)

## Linked issues

closes: #849

## Details

1. Add JSDoc for authentication code
2. Move `TeamsSsoSettings` out of `TeamsBotSsoPromt`, as it's not only
for this prompt

## Attestation Checklist

- [x] My code follows the style guidelines of this project

- I have checked for/fixed spelling, linting, and other errors
- I have commented my code for clarity
- I have made corresponding changes to the documentation (we use
[TypeDoc](https://typedoc.org/) to document our code)
- My changes generate no new warnings
- I have added tests that validates my changes, and provides sufficient
test coverage. I have tested with:
  - Local testing
  - E2E testing in Teams
- New and existing unit tests pass locally with my changes

Author: blackchoey

js/packages/teams-ai/src/authentication/AdaptiveCardAuthenticationBase.ts

@@ -26,8 +26,16 @@ export interface AdaptiveCardLoginRequest {
 
 /**
  * @internal
+ * 
+ * Base class to handle adaptive card authentication.
  */
 export abstract class AdaptiveCardAuthenticationBase {
+
+    /**
+     * Authenticates the user.
+     * @param {TurnContext} context - The turn context.
+     * @returns {Promise<string | undefined>} - The authentication token, or undefined if authentication failed. Teams will ask user to sign-in if authentication failed.
+     */
     public async authenticate(context: TurnContext): Promise<string | undefined> {
         const value = context.activity.value;
 
@@ -90,15 +98,36 @@ export abstract class AdaptiveCardAuthenticationBase {
         return;
     }
 
+    /**
+     * Checks if the activity is a valid Adaptive Card activity that supports authentication.
+     * @param context - The turn context.
+     * @returns A boolean indicating if the activity is valid.
+     */
     public isValidActivity(context: TurnContext): boolean {
         return context.activity.type == ActivityTypes.Invoke && context.activity.name == ACTION_INVOKE_NAME;
     }
 
+    /**
+     * Handles the SSO token exchange.
+     * @param context - The turn context.
+     * @returns A promise that resolves to the token response or undefined if token exchange failed.
+     */
     public abstract handleSsoTokenExchange(
         context: TurnContext
     ): Promise<TokenResponse | undefined>
 
+    /**
+     * Handles the user sign-in.
+     * @param context - The turn context.
+     * @param magicCode - The magic code from user sign-in.
+     * @returns A promise that resolves to the token response or undefined if failed to verify the magic code.
+     */
     public abstract handleUserSignIn(context: TurnContext, magicCode: string): Promise<TokenResponse | undefined>
 
+    /**
+     * Gets the login request for Adaptive Card authentication.
+     * @param context - The turn context.
+     * @returns A promise that resolves to the login request.
+     */
     public abstract getLoginRequest(context: TurnContext): Promise<AdaptiveCardLoginRequest>
 }

js/packages/teams-ai/src/authentication/Authentication.ts

@@ -16,7 +16,7 @@ import { MessageExtensionAuthenticationBase } from './MessageExtensionAuthentica
 import { BotAuthenticationBase, deleteTokenFromState, setTokenInState } from './BotAuthenticationBase';
 import * as UserTokenAccess from './UserTokenAccess';
 import { AdaptiveCardAuthenticationBase } from './AdaptiveCardAuthenticationBase';
-import { TeamsSsoSettings } from './TeamsBotSsoPrompt';
+import { TeamsSsoSettings } from './TeamsSsoSettings';
 import { OAuthPromptMessageExtensionAuthentication } from './OAuthMessageExtensionAuthentication';
 import { OAuthBotAuthentication } from './OAuthBotAuthentication';
 import { TeamsSsoBotAuthentication } from './TeamsSsoBotAuthentication';

js/packages/teams-ai/src/authentication/BotAuthenticationBase.ts

@@ -22,13 +22,22 @@ interface UserAuthState {
 
 /**
  * @internal
+ * 
+ * Base class to handle Teams conversational bot authentication.
+ * @template TState - The type of the turn state.
  */
 export abstract class BotAuthenticationBase<TState extends TurnState> {
     protected _storage: Storage;
     protected _settingName: string;
     private _userSignInSuccessHandler?: (context: TurnContext, state: TState) => Promise<void>;
     private _userSignInFailureHandler?: (context: TurnContext, state: TState, error: AuthError) => Promise<void>;
 
+    /**
+     * Creates a new instance of BotAuthenticationBase.
+     * @param {Application<TState>} app - The application instance.
+     * @param {string} settingName - The name of the setting.
+     * @param {Storage} [storage] - The storage to save states.
+     */
     public constructor(app: Application<TState>, settingName: string, storage?: Storage) {
         this._settingName = settingName;
 
@@ -51,6 +60,12 @@ export abstract class BotAuthenticationBase<TState extends TurnState> {
         );
     }
 
+    /**
+     * Authenticates the user.
+     * @param {TurnContext} context - The turn context.
+     * @param {TState} state - The turn state.
+     * @returns {Promise<string | undefined>} - The authentication token, or undefined if authentication failed.
+     */
     public async authenticate(context: TurnContext, state: TState): Promise<string | undefined> {
         // Get property names to use
         const userAuthStatePropertyName = this.getUserAuthStatePropertyName(context);
@@ -82,6 +97,11 @@ export abstract class BotAuthenticationBase<TState extends TurnState> {
         return undefined;
     }
 
+    /**
+     * Checks if the activity is a valid message activity
+     * @param {TurnContext} context - The turn context.
+     * @returns {boolean} - True if the activity is a valid message activity.
+     */
     public isValidActivity(context: TurnContext): boolean {
         // Should be a message activity with non-empty text property.
         return (
@@ -112,6 +132,11 @@ export abstract class BotAuthenticationBase<TState extends TurnState> {
         this._userSignInFailureHandler = handler;
     }
 
+    /**
+     * Handles the signin/verifyState activity. The onUserSignInSuccess and onUserSignInFailure handlers will be called based on the result.
+     * @param {TurnContext} context - The turn context.
+     * @param {TState} state - The turn state.
+     */
     public async handleSignInActivity(context: TurnContext, state: TState): Promise<void> {
         try {
             const userDialogStatePropertyName = this.getUserDialogStatePropertyName(context);
@@ -149,6 +174,11 @@ export abstract class BotAuthenticationBase<TState extends TurnState> {
         }
     }
 
+    /**
+     * Deletes the user auth state and user dialog state from the turn state. So that the next message can start a new authentication flow.
+     * @param {TurnContext} context - The turn context.
+     * @param {TState} state - The turn state.
+     */
     public deleteAuthFlowState(context: TurnContext, state: TState) {
         // Delete user auth state
         const userAuthStatePropertyName = this.getUserAuthStatePropertyName(context);
@@ -163,10 +193,20 @@ export abstract class BotAuthenticationBase<TState extends TurnState> {
         }
     }
 
+    /**
+     * Gets the property name for storing user authentication state.
+     * @param {TurnContext} context - The turn context.
+     * @returns {string} - The property name.
+     */
     public getUserAuthStatePropertyName(context: TurnContext): string {
         return `__${context.activity.from.id}:${this._settingName}:Bot:AuthState__`;
     }
 
+    /**
+     * Gets the property name for storing user dialog state.
+     * @param {TurnContext} context - The turn context.
+     * @returns {string} - The property name.
+     */
     public getUserDialogStatePropertyName(context: TurnContext): string {
         return `__${context.activity.from.id}:${this._settingName}:DialogState__`;
     }
@@ -188,12 +228,26 @@ export abstract class BotAuthenticationBase<TState extends TurnState> {
         return context.activity.type === ActivityTypes.Invoke && context.activity.name === tokenExchangeOperationName;
     }
 
+    /**
+     * Run or continue the authentication dialog.
+     * @param {TurnContext} context - The turn context.
+     * @param {TState} state - The turn state.
+     * @param {string} dialogStateProperty - The property name for storing dialog state.
+     * @returns {Promise<DialogTurnResult<TokenResponse>>} - A promise that resolves to the dialog turn result containing the token response.
+     */
     public abstract runDialog(
         context: TurnContext,
         state: TState,
         dialogStateProperty: string
     ): Promise<DialogTurnResult<TokenResponse>>;
 
+    /**
+     * Continues the authentication dialog.
+     * @param {TurnContext} context - The turn context.
+     * @param {TState} state - The turn state.
+     * @param {string} dialogStateProperty - The property name for storing dialog state.
+     * @returns {Promise<DialogTurnResult<TokenResponse>>} - A promise that resolves to the dialog turn result containing the token response.
+     */
     public abstract continueDialog(
         context: TurnContext,
         state: TState,

js/packages/teams-ai/src/authentication/MessageExtensionAuthenticationBase.ts

@@ -3,8 +3,15 @@ import { MessageExtensionsInvokeNames } from '../MessageExtensions';
 
 /**
  * @internal
+ * Base class to handle authentication for Teams Message Extension.
  */
 export abstract class MessageExtensionAuthenticationBase {
+
+    /**
+     * Authenticates the user.
+     * @param {TurnContext} context - The turn context.
+     * @returns {Promise<string | undefined>} - The authentication token, or undefined if authentication failed. Teams will ask user to sign-in if authentication failed.
+     */
     public async authenticate(context: TurnContext): Promise<string | undefined> {
         const value = context.activity.value;
         const tokenExchangeRequest = value.authentication;
@@ -75,6 +82,11 @@ export abstract class MessageExtensionAuthenticationBase {
         return;
     }
 
+    /**
+     * Checks if the activity is a valid Message Extension activity that supports authentication.
+     * @param {TurnContext} context - The turn context.
+     * @returns {boolean} - A boolean indicating if the activity is valid.
+     */
     public isValidActivity(context: TurnContext): boolean {
         return (
             context.activity.type == ActivityTypes.Invoke &&
@@ -85,11 +97,27 @@ export abstract class MessageExtensionAuthenticationBase {
         );
     }
 
+    /**
+     * Handles the SSO token exchange.
+     * @param {TurnContext} context - The turn context.
+     * @returns {Promise<TokenResponse | undefined>} - A promise that resolves to the token response or undefined if token exchange failed.
+     */
     public abstract handleSsoTokenExchange(
         context: TurnContext
     ): Promise<TokenResponse | undefined>
 
+    /**
+     * Handles the user sign-in.
+     * @param {TurnContext} context - The turn context.
+     * @param {string} magicCode - The magic code from user sign-in.
+     * @returns {Promise<TokenResponse | undefined>} - A promise that resolves to the token response or undefined if failed to verify the magic code.
+     */
     public abstract handleUserSignIn(context: TurnContext, magicCode: string): Promise<TokenResponse | undefined>
 
+    /**
+     * Gets the sign-in link for the user.
+     * @param {TurnContext} context - The turn context.
+     * @returns {Promise<string | undefined>} - A promise that resolves to the sign-in link or undefined if no sign-in link available.
+     */
     public abstract getSignInLink(context: TurnContext): Promise<string | undefined>
 }

js/packages/teams-ai/src/authentication/OAuthAdaptiveCardAuthentication.ts

@@ -6,11 +6,26 @@ import { AdaptiveCardAuthenticationBase, AdaptiveCardLoginRequest } from './Adap
 import { AuthError, OAuthSettings } from './Authentication';
 import * as UserTokenAccess from './UserTokenAccess';
 
+/**
+ * @internal
+ * 
+ * Handles authentication for Adaptive Cards in Teams.
+ */
 export class OAuthAdaptiveCardAuthentication extends AdaptiveCardAuthenticationBase {
+
+    /**
+     * Creates a new instance of OAuthAdaptiveCardAuthentication.
+     * @param settings The OAuthSettings.
+     */
     public constructor(private readonly settings: OAuthSettings) {
         super();
     }
 
+    /**
+     * Handles the SSO token exchange.
+     * @param context The turn context.
+     * @returns A promise that resolves to the token response or undefined if token exchange failed.
+     */
     public async handleSsoTokenExchange(context: TurnContext): Promise<TokenResponse | undefined> {
         const tokenExchangeRequest = context.activity.value.authentication;
 
@@ -21,10 +36,21 @@ export class OAuthAdaptiveCardAuthentication extends AdaptiveCardAuthenticationB
         return await UserTokenAccess.exchangeToken(context, this.settings, tokenExchangeRequest);
     }
 
+    /**
+     * Handles the signin/verifyState activity.
+     * @param context The turn context.
+     * @param magicCode The magic code from sign-in.
+     * @returns A promise that resolves to undefined. The parent class will trigger silentAuth again.
+     */
     public async handleUserSignIn(context: TurnContext, magicCode: string): Promise<TokenResponse | undefined> {
         return await UserTokenAccess.getUserToken(context, this.settings, magicCode);
     }
 
+    /**
+     * Gets the sign-in link for the user.
+     * @param context The turn context.
+     * @returns A promise that resolves to the sign-in link or undefined if no sign-in link available.
+     */
     public async getLoginRequest(context: TurnContext): Promise<AdaptiveCardLoginRequest> {
         const signInResource = await UserTokenAccess.getSignInResource(context, this.settings);
         const signInLink = signInResource.signInLink;

js/packages/teams-ai/src/authentication/OAuthBotAuthentication.ts

@@ -16,9 +16,22 @@ import { Application } from '../Application';
 import { TurnState } from '../TurnState';
 import { TurnStateProperty } from '../TurnStateProperty';
 
+/**
+ * @internal
+ * 
+ * Handles authentication for Teams bots.
+ * @template TState - The type of the turn state object.
+ */
 export class OAuthBotAuthentication<TState extends TurnState> extends BotAuthenticationBase<TState> {
     private _oauthPrompt: OAuthPrompt;
 
+    /**
+     * Initializes a new instance of the OAuthBotAuthentication class.
+     * @param app - The application object.
+     * @param oauthPromptSettings - The settings for OAuthPrompt.
+     * @param settingName - The name of the setting.
+     * @param storage - The storage object for storing state.
+     */
     public constructor(
         app: Application<TState>,
         oauthPromptSettings: OAuthPromptSettings, // Child classes will have different types for this
@@ -34,6 +47,13 @@ export class OAuthBotAuthentication<TState extends TurnState> extends BotAuthent
         app.adapter.use(new FilteredTeamsSSOTokenExchangeMiddleware(this._storage, oauthPromptSettings.connectionName));
     }
 
+    /**
+     * Run or continue the OAuthPrompt dialog and returns the result.
+     * @param context - The turn context object.
+     * @param state - The turn state object.
+     * @param dialogStateProperty - The name of the dialog state property.
+     * @returns A promise that resolves to the dialog turn result containing the token response.
+     */
     public async runDialog(
         context: TurnContext,
         state: TState,
@@ -47,6 +67,14 @@ export class OAuthBotAuthentication<TState extends TurnState> extends BotAuthent
         return results;
     }
 
+    
+    /**
+     * Continue the OAuthPrompt dialog and returns the result.
+     * @param context - The turn context object.
+     * @param state - The turn state object.
+     * @param dialogStateProperty - The name of the dialog state property.
+     * @returns A promise that resolves to the dialog turn result containing the token response.
+     */
     public async continueDialog(
         context: TurnContext,
         state: TState,
@@ -56,6 +84,13 @@ export class OAuthBotAuthentication<TState extends TurnState> extends BotAuthent
         return await dialogContext.continueDialog();
     }
 
+    /**
+     * Creates a new DialogContext for OAuthPrompt.
+     * @param context - The turn context object.
+     * @param state - The turn state object.
+     * @param dialogStateProperty - The name of the dialog state property.
+     * @returns A promise that resolves to the dialog context.
+     */
     private async createDialogContext(
         context: TurnContext,
         state: TState,