[v5] Update typedoc comments for requests (#8218)

This PR updates our comments for various requests as this helps our
typedoc documentation.

---------

Co-authored-by: Thomas Norling <[email protected]>

Author: jo-arroyo

change/@azure-msal-browser-c77a5d91-8026-4a7c-9a4d-7c07f66d8208.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Update typedoc comments for requests #8218",
+  "packageName": "@azure/msal-browser",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

change/@azure-msal-common-f13438e9-1b16-4fcf-a97c-5a48e5e6887b.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Update typedoc comments for requests #8218",
+  "packageName": "@azure/msal-common",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

change/@azure-msal-node-ab1aea4a-e097-4a30-b835-20e7f6e88725.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Update typedoc comments for requests #8218",
+  "packageName": "@azure/msal-node",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

lib/msal-browser/apiReview/msal-browser.api.md

@@ -142,7 +142,7 @@ export { AuthErrorCodes }
 
 // Warning: (ae-missing-release-tag) "AuthorizationCodeRequest" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export type AuthorizationCodeRequest = Partial<Omit<CommonAuthorizationCodeRequest, "code" | "enableSpaAuthorizationCode">> & {
     code?: string;
     nativeAccountId?: string;

lib/msal-browser/src/request/AuthorizationCodeRequest.ts

@@ -5,12 +5,30 @@
 
 import { CommonAuthorizationCodeRequest } from "@azure/msal-common/browser";
 
+/**
+ * AuthorizationCodeRequest: Request object passed by browser clients to exchange an authorization code for tokens.
+ */
 export type AuthorizationCodeRequest = Partial<
     Omit<CommonAuthorizationCodeRequest, "code" | "enableSpaAuthorizationCode">
 > & {
+    /**
+     * The authorization_code that the user acquired in the first leg of the flow.
+     */
     code?: string;
+    /**
+     * Identifier for the native account when integrating with native or brokered experiences.
+     */
     nativeAccountId?: string;
+    /**
+     * Hostname for the Microsoft Cloud instance's Graph endpoint (for example, graph.microsoft.com).
+     */
     cloudGraphHostName?: string;
+    /**
+     * Hostname for the Microsoft Graph endpoint when overriding defaults.
+     */
     msGraphHost?: string;
+    /**
+     * Hostname for the Azure AD cloud instance that issued the authorization code.
+     */
     cloudInstanceHostName?: string;
 };

lib/msal-browser/src/request/ClearCacheRequest.ts

@@ -7,10 +7,14 @@ import { AccountInfo } from "@azure/msal-common/browser";
 
 /**
  * ClearCacheRequest
- * - correlationId          - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
- * - account                - Account object that will be logged out of. All tokens tied to this account will be cleared.
  */
 export type ClearCacheRequest = {
+    /**
+     * Unique GUID set per request to trace a request end-to-end for telemetry purposes.
+     */
     correlationId?: string;
+    /**
+     * Account object that will be logged out of. All tokens tied to this account will be cleared.
+     */
     account?: AccountInfo | null;
 };

lib/msal-browser/src/request/EndSessionPopupRequest.ts

@@ -8,19 +8,22 @@ import { PopupWindowAttributes } from "./PopupWindowAttributes.js";
 
 /**
  * EndSessionPopupRequest
- * - account                - Account object that will be logged out of. All tokens tied to this account will be cleared.
- * - postLogoutRedirectUri  - URI to navigate to after logout page inside the popup. Required to ensure popup can be closed.
- * - authority              - Authority to send logout request to.
- * - correlationId          - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
- * - idTokenHint            - ID Token used by B2C to validate logout if required by the policy
- * - mainWindowRedirectUri  - URI to navigate the main window to after logout is complete
- * - popupWindowAttributes  - Optional popup window attributes. popupSize with height and width, and popupPosition with top and left can be set.
- * - logoutHint             - A string that specifies the account that is being logged out in order to skip the server account picker on logout
- * - popupWindowParent      - Optional window object to use as the parent when opening popup windows. Uses global `window` if not given.
  */
 export type EndSessionPopupRequest = Partial<CommonEndSessionRequest> & {
+    /**
+     * Authority to send logout request to.
+     */
     authority?: string;
+    /**
+     * URI to navigate the main window to after logout is complete
+     */
     mainWindowRedirectUri?: string;
+    /**
+     * Optional popup window attributes. popupSize with height and width, and popupPosition with top and left can be set.
+     */
     popupWindowAttributes?: PopupWindowAttributes;
+    /**
+     * Optional window object to use as the parent when opening popup windows. Uses global `window` if not given.
+     */
     popupWindowParent?: Window;
 };

lib/msal-browser/src/request/EndSessionRequest.ts

@@ -7,13 +7,10 @@ import { CommonEndSessionRequest } from "@azure/msal-common/browser";
 
 /**
  * EndSessionRequest
- * - account                - Account object that will be logged out of. All tokens tied to this account will be cleared.
- * - postLogoutRedirectUri  - URI to navigate to after logout page.
- * - authority              - Authority to send logout request to.
- * - correlationId          - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
- * - idTokenHint            - ID Token used by B2C to validate logout if required by the policy
- * - logoutHint             - A string that specifies the account that is being logged out in order to skip the server account picker on logout
  */
 export type EndSessionRequest = Partial<CommonEndSessionRequest> & {
+    /**
+     * Authority to send logout request.
+     */
     authority?: string;
 };

lib/msal-browser/src/request/InitializeApplicationRequest.ts

@@ -5,9 +5,10 @@
 
 /**
  * InitializeApplicationRequest: Request object passed by user to initialize application
- *
- * - correlationId              - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
  */
 export type InitializeApplicationRequest = {
+    /**
+     * Unique GUID set per request to trace a request end-to-end for telemetry purposes.
+     */
     correlationId?: string;
 };

lib/msal-browser/src/request/PopupRequest.ts

@@ -9,30 +9,6 @@ import { PopupWindowAttributes } from "./PopupWindowAttributes.js";
 /**
  * PopupRequest: Request object passed by user to retrieve a Code from the
  * server (first leg of authorization code grant flow) with a popup window.
- *
- * - scopes                     - Array of scopes the application is requesting access to.
- * - authority                  - Url of the authority which the application acquires tokens from.
- * - correlationId              - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
- * - redirectUri                - The redirect URI where authentication responses can be received by your application. It must exactly match one of the redirect URIs registered in the Azure portal.
- * - extraScopesToConsent       - Scopes for a different resource when the user needs consent upfront.
- * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred. For security and privacy reasons, we do not recommend putting URLs or other sensitive data directly in the state parameter. Instead, use a key or identifier that corresponds to data stored in browser storage (e.g., localStorage, sessionStorage), allowing your app to securely reference the necessary data after authentication.
- * - prompt                     - Indicates the type of user interaction that is required.
- *          login: will force the user to enter their credentials on that request, negating single-sign on
- *          none:  will ensure that the user isn't presented with any interactive prompt. if request can't be completed via single-sign on, the endpoint will return an interaction_required error
- *          consent: will the trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions to the app
- *          select_account: will interrupt single sign-=on providing account selection experience listing all the accounts in session or any remembered accounts or an option to choose to use a different account
- *          create: will direct the user to the account creation experience instead of the log in experience
- *          no_session: will not read existing session token when authenticating the user. Upon user being successfully authenticated, EVO won’t create a new session for the user. FOR INTERNAL USE ONLY.
- * - loginHint                  - Can be used to pre-fill the username/email address field of the sign-in page for the user, if you know the username/email address ahead of time. Often apps use this parameter during re-authentication, having already extracted the username from a previous sign-in using the login_hint or preferred_username claim.
- * - sid                        - Session ID, unique identifier for the session. Available as an optional claim on ID tokens.
- * - domainHint                 - Provides a hint about the tenant or domain that the user should use to sign in. The value of the domain hint is a registered domain for the tenant.
- * - extraQueryParameters       - String to string map of custom query parameters added to outgoing token service requests
- * - extraParameters            - String to string map of custom query parameters added to outgoing token service requests
- * - claims                     - In cases where Azure AD tenant admin has enabled conditional access policies, and the policy has not been met, exceptions will contain claims that need to be consented to.
- * - nonce                      - A value included in the request that is returned in the id token. A randomly generated unique value is typically used to mitigate replay attacks.
- * - popupWindowAttributes      - Optional popup window attributes. popupSize with height and width, and popupPosition with top and left can be set.
- * - popupWindowParent          - Optional window object to use as the parent when opening popup windows. Uses global `window` if not given.
- * - overrideInteractionInProgress - Optional flag to allow overriding an existing interaction_in_progress state for popup flows. **WARNING**: Use with caution! For usage details and examples, see the [login-user.md](../../../docs/login-user.md#handling-interaction_in_progress-errors) documentation.
  */
 
 export type PopupRequest = Partial<
@@ -46,8 +22,20 @@ export type PopupRequest = Partial<
         | "platformBroker"
     >
 > & {
+    /**
+     * Array of scopes the application is requesting access to.
+     */
     scopes: Array<string>;
+    /**
+     * Optional popup window attributes. popupSize with height and width, and popupPosition with top and left can be set.
+     */
     popupWindowAttributes?: PopupWindowAttributes;
+    /**
+     * Optional window object to use as the parent when opening popup windows. Uses global `window` if not given.
+     */
     popupWindowParent?: Window;
+    /**
+     * Optional flag to allow overriding an existing interaction_in_progress state for popup flows. **WARNING**: Use with caution! For usage details and examples, see the [login-user.md](../../../docs/login-user.md#handling-interaction_in_progress-errors) documentation.
+     */
     overrideInteractionInProgress?: boolean;
 };