[v5] Add interrupted_user to InteractionRequired Error list (#8322)

This pull request enhances the `@azure/msal-common` package by improving
the documentation and public exposure of several error codes, and by
adding support for a new error code (`interrupted_user`) to the list of
interaction required errors. These changes make error handling more
robust and transparent for consumers of the library.

**Error code improvements and additions:**

* Added a new error code, `interrupted_user`, to the
`InteractionRequiredAuthErrorCodes` enum and included it in the lists of
interaction required errors. This code indicates that the user is in an
interrupted state and requires interaction to proceed.
[[1]](diffhunk://#diff-7f0fe7571801f31eb8b7836af2cc65e994162a583145a4469ce94d92b1d3ac03R1-R7)
[[2]](diffhunk://#diff-09087b913ebbfa828e5f36b7476a400328e0a7131db84f622cc5f6994759a117L2663-R2665)
[[3]](diffhunk://#diff-175e2da3fd2f20fd01bf24622c10e9a9a44b468507420611113b1917ea47f00bR19)
[[4]](diffhunk://#diff-175e2da3fd2f20fd01bf24622c10e9a9a44b468507420611113b1917ea47f00bR30)
[[5]](diffhunk://#diff-9b9e373ecd25242838c370efe898168af89089ced090e293f571d816f02e8cf0L6-R51)
* Improved documentation and made the following error codes explicitly
public: `badToken`, `consentRequired`, `interactionRequired`,
`loginRequired`, `nativeAccountUnavailable`, `noTokensFound`,
`refreshTokenExpired`, and `uxNotAllowed`. This clarifies their usage
and ensures they are part of the package's public API.
[[1]](diffhunk://#diff-09087b913ebbfa828e5f36b7476a400328e0a7131db84f622cc5f6994759a117L944-R944)
[[2]](diffhunk://#diff-09087b913ebbfa828e5f36b7476a400328e0a7131db84f622cc5f6994759a117L1701-R1699)
[[3]](diffhunk://#diff-09087b913ebbfa828e5f36b7476a400328e0a7131db84f622cc5f6994759a117L2638-R2634)
[[4]](diffhunk://#diff-09087b913ebbfa828e5f36b7476a400328e0a7131db84f622cc5f6994759a117L2993-R2991)
[[5]](diffhunk://#diff-09087b913ebbfa828e5f36b7476a400328e0a7131db84f622cc5f6994759a117L3069-R3065)
[[6]](diffhunk://#diff-09087b913ebbfa828e5f36b7476a400328e0a7131db84f622cc5f6994759a117L3195-R3189)
[[7]](diffhunk://#diff-09087b913ebbfa828e5f36b7476a400328e0a7131db84f622cc5f6994759a117L3749-R3741)
[[8]](diffhunk://#diff-09087b913ebbfa828e5f36b7476a400328e0a7131db84f622cc5f6994759a117L4638-R4628)
[[9]](diffhunk://#diff-9b9e373ecd25242838c370efe898168af89089ced090e293f571d816f02e8cf0L6-R51)

**Documentation enhancements:**

* Added or improved JSDoc comments for all error code exports in
`InteractionRequiredAuthErrorCodes.ts`, providing clear descriptions for
each code and marking them as `@public`.

Author: hectormmg

change/@azure-msal-common-bbfcc309-453b-4080-a808-81678cb08b13.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Add interrupted_user to InteractionRequired Error list (#8322)",
+  "packageName": "@azure/msal-common",
+  "email": "hemoral@microsoft.com",
+  "dependentChangeType": "patch"
+}

docs/errors.md

@@ -302,6 +302,11 @@ This error occurs when MSAL.js surpasses the allotted storage limit when attempt
 
 -   `canShowUI` flag in Edge was set to false. User interaction required on web page. Please invoke an interactive API to resolve.
 
+
+### `interrupted_user`
+
+-   The user could not be authenticated due to an interrupted state. Please invoke an interactive API to resolve.
+
 ## JOSE header errors
 
 ### `missing_kid_error`

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

@@ -941,9 +941,7 @@ export type AzureRegionConfiguration = {
     environmentRegion: string | undefined;
 };
 
-// Warning: (ae-missing-release-tag) "badToken" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 const badToken = "bad_token";
 
 // Warning: (ae-missing-release-tag) "BaseAuthRequest" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -1698,9 +1696,7 @@ export type CommonSilentFlowRequest = BaseAuthRequest & {
     refreshTokenExpirationOffsetSeconds?: number;
 };
 
-// Warning: (ae-missing-release-tag) "consentRequired" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 const consentRequired = "consent_required";
 
 declare namespace Constants {
@@ -2635,9 +2631,7 @@ const INSTANCE_AWARE = "instance_aware";
 // @public (undocumented)
 function instrumentBrokerParams(parameters: Map<string, string>, correlationId?: string, performanceClient?: IPerformanceClient): void;
 
-// Warning: (ae-missing-release-tag) "interactionRequired" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 const interactionRequired = "interaction_required";
 
 // Warning: (ae-missing-release-tag) "InteractionRequiredAuthError" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -2660,11 +2654,15 @@ declare namespace InteractionRequiredAuthErrorCodes {
         interactionRequired,
         consentRequired,
         loginRequired,
-        badToken
+        badToken,
+        interruptedUser
     }
 }
 export { InteractionRequiredAuthErrorCodes }
 
+// @public
+const interruptedUser = "interrupted_user";
+
 // Warning: (ae-missing-release-tag) "IntFields" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -2990,9 +2988,7 @@ export type LoggerOptions = {
 // @public (undocumented)
 const LOGIN_HINT = "login_hint";
 
-// Warning: (ae-missing-release-tag) "loginRequired" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 const loginRequired = "login_required";
 
 // Warning: (ae-missing-release-tag) "LogLevel" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -3066,9 +3062,7 @@ const multipleMatchingTokens = "multiple_matching_tokens";
 // @public (undocumented)
 const NATIVE_BROKER = "nativebroker";
 
-// Warning: (ae-missing-release-tag) "nativeAccountUnavailable" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 const nativeAccountUnavailable = "native_account_unavailable";
 
 // Warning: (ae-missing-release-tag) "NativeRequest" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -3192,9 +3186,7 @@ const NOT_APPLICABLE = "N/A";
 // @public (undocumented)
 const NOT_AVAILABLE = "Not Available";
 
-// Warning: (ae-missing-release-tag) "noTokensFound" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 const noTokensFound = "no_tokens_found";
 
 // Warning: (ae-missing-release-tag) "nowSeconds" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -3746,9 +3738,7 @@ export type RefreshTokenEntity = CredentialEntity & {
     expiresOn?: string;
 };
 
-// Warning: (ae-missing-release-tag) "refreshTokenExpired" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 const refreshTokenExpired = "refresh_token_expired";
 
 // Warning: (ae-missing-release-tag) "REGIONAL_AUTH_PUBLIC_CLOUD_SUFFIX" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -4635,9 +4625,7 @@ export { UrlUtils }
 // @public (undocumented)
 const userCanceled = "user_canceled";
 
-// Warning: (ae-missing-release-tag) "uxNotAllowed" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public (undocumented)
+// @public
 const uxNotAllowed = "ux_not_allowed";
 
 // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen

lib/msal-common/src/error/InteractionRequiredAuthError.ts

@@ -16,6 +16,7 @@ export const InteractionRequiredServerErrorMessage = [
     InteractionRequiredAuthErrorCodes.loginRequired,
     InteractionRequiredAuthErrorCodes.badToken,
     InteractionRequiredAuthErrorCodes.uxNotAllowed,
+    InteractionRequiredAuthErrorCodes.interruptedUser,
 ];
 
 export const InteractionRequiredAuthSubErrorMessage = [
@@ -26,6 +27,7 @@ export const InteractionRequiredAuthSubErrorMessage = [
     "consent_required",
     "bad_token",
     "ux_not_allowed",
+    "interrupted_user",
 ];
 
 /**

lib/msal-common/src/error/InteractionRequiredAuthErrorCodes.ts

@@ -3,14 +3,49 @@
  * Licensed under the MIT License.
  */
 
-// Codes defined by MSAL
+/**
+ * MSAL-defined interaction required error code indicating no tokens are found in cache.
+ * @public
+ */
 export const noTokensFound = "no_tokens_found";
+/**
+ * MSAL-defined error code indicating a native account is unavailable on the platform.
+ * @public
+ */
 export const nativeAccountUnavailable = "native_account_unavailable";
+/**
+ * MSAL-defined error code indicating the refresh token has expired and user interaction is needed.
+ * @public
+ */
 export const refreshTokenExpired = "refresh_token_expired";
+/**
+ * MSAL-defined error code indicating UI/UX is not allowed (e.g., blocked by policy), requiring alternate interaction.
+ * @public
+ */
 export const uxNotAllowed = "ux_not_allowed";
 
-// Codes potentially returned by server
+/**
+ * Server-originated error code indicating interaction is required to complete the request.
+ * @public
+ */
 export const interactionRequired = "interaction_required";
+/**
+ * Server-originated error code indicating user consent is required.
+ * @public
+ */
 export const consentRequired = "consent_required";
+/**
+ * Server-originated error code indicating user login is required.
+ * @public
+ */
 export const loginRequired = "login_required";
+/**
+ * Server-originated error code indicating the token is invalid or corrupted.
+ * @public
+ */
 export const badToken = "bad_token";
+/**
+ * Server-originated error code indicating the user is in an interrupted state and interaction is required.
+ * @public
+ */
+export const interruptedUser = "interrupted_user";

lib/msal-common/test/error/InteractionRequiredAuthError.spec.ts

@@ -3,6 +3,8 @@ import {
     InteractionRequiredAuthSubErrorMessage,
     InteractionRequiredServerErrorMessage,
     isInteractionRequiredError,
+    createInteractionRequiredAuthError,
+    InteractionRequiredAuthErrorCodes,
 } from "../../src/error/InteractionRequiredAuthError";
 import { AuthError } from "../../src/error/AuthError";
 
@@ -95,4 +97,25 @@ describe("InteractionRequiredAuthError.ts Class Unit Tests", () => {
             ).toBe(false);
         });
     });
+
+    describe("createInteractionRequiredAuthError()", () => {
+        it("produces non-empty messages for all mapped codes", () => {
+            const codes = [
+                InteractionRequiredAuthErrorCodes.noTokensFound,
+                InteractionRequiredAuthErrorCodes.nativeAccountUnavailable,
+                InteractionRequiredAuthErrorCodes.refreshTokenExpired,
+                InteractionRequiredAuthErrorCodes.badToken,
+                InteractionRequiredAuthErrorCodes.uxNotAllowed,
+                InteractionRequiredAuthErrorCodes.interruptedUser,
+            ];
+
+            codes.forEach((code) => {
+                const err = createInteractionRequiredAuthError(code);
+                expect(err instanceof InteractionRequiredAuthError).toBe(true);
+                expect(err.errorCode).toBe(code);
+                expect(typeof err.errorMessage).toBe("string");
+                expect(err.errorMessage.length).toBeGreaterThan(0);
+            });
+        });
+    });
 });