feat(clerk-js,shared,types,localizations): New client_mismatch status for email link sign in/up (#3367)

* feat(clerk-js,shared,types,localizations): New client_mismatch status for email link sign in/up

* feat(localizations): Update email link client_mistmatch messages

Author: mzhong9723

.changeset/chilled-laws-pump.md

@@ -0,0 +1,5 @@
+---
+'@clerk/localizations': minor
+---
+
+Added new keys for email link verification under `signIn.emailLink.clientMismatch` and `signUp.emailLink.clientMismatch`

.changeset/tricky-tomatoes-repair.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Introduce new `client_mismatch` verification status for email link sign-in and sign-up. This error (and its message) will be shown if a verification link was opened in another device/browser from which the user initiated the sign-in/sign-up attempt. This functionality needs to be enabled in the Clerk dashboard.

packages/clerk-js/src/core/clerk.ts

@@ -981,6 +981,8 @@ export class Clerk implements ClerkInterface {
     const verificationStatus = getClerkQueryParam('__clerk_status');
     if (verificationStatus === 'expired') {
       throw new EmailLinkError(EmailLinkErrorCode.Expired);
+    } else if (verificationStatus === 'client_mismatch') {
+      throw new EmailLinkError(EmailLinkErrorCode.ClientMismatch);
     } else if (verificationStatus !== 'verified') {
       throw new EmailLinkError(EmailLinkErrorCode.Failed);
     }

packages/clerk-js/src/ui/common/EmailLinkCompleteFlowCard.tsx

@@ -24,6 +24,10 @@ const signInLocalizationKeys = {
     title: localizationKeys('signIn.emailLink.expired.title'),
     subtitle: localizationKeys('signIn.emailLink.expired.subtitle'),
   },
+  client_mismatch: {
+    title: localizationKeys('signIn.emailLink.clientMismatch.title'),
+    subtitle: localizationKeys('signIn.emailLink.clientMismatch.subtitle'),
+  },
 };
 
 const signUpLocalizationKeys = {
@@ -40,6 +44,10 @@ const signUpLocalizationKeys = {
     ...signInLocalizationKeys.loading,
     title: localizationKeys('signUp.emailLink.loading.title'),
   },
+  client_mismatch: {
+    ...signInLocalizationKeys.client_mismatch,
+    subtitle: localizationKeys('signUp.emailLink.clientMismatch.subtitle'),
+  },
 };
 
 export const SignInEmailLinkFlowComplete = withCardStateProvider((props: Omit<EmailLinkVerifyProps, 'texts'>) => {

packages/clerk-js/src/ui/common/EmailLinkStatusCard.tsx

@@ -20,6 +20,7 @@ const StatusToIcon: Record<Exclude<VerificationStatus, 'loading'>, React.Compone
   verified_switch_tab: SwitchArrows,
   expired: ExclamationTriangle,
   failed: ExclamationTriangle,
+  client_mismatch: ExclamationTriangle,
 };
 
 const statusToColor = (theme: InternalTheme, status: Exclude<VerificationStatus, 'loading'>) =>
@@ -28,6 +29,7 @@ const statusToColor = (theme: InternalTheme, status: Exclude<VerificationStatus,
     verified_switch_tab: theme.colors.$primary500,
     expired: theme.colors.$warning500,
     failed: theme.colors.$danger500,
+    client_mismatch: theme.colors.$warning500,
   }[status]);
 
 export const EmailLinkStatusCard = (props: EmailLinkStatusCardProps) => {

packages/clerk-js/src/ui/common/EmailLinkVerify.tsx

@@ -43,6 +43,9 @@ export const EmailLinkVerify = (props: EmailLinkVerifyProps) => {
       if (isEmailLinkError(err) && err.code === EmailLinkErrorCode.Expired) {
         status = 'expired';
       }
+      if (isEmailLinkError(err) && err.code === EmailLinkErrorCode.ClientMismatch) {
+        status = 'client_mismatch';
+      }
       setVerificationStatus(status);
     }
   };

packages/clerk-js/src/utils/getClerkQueryParam.ts

@@ -26,7 +26,13 @@ type ClerkQueryParamsToValuesMap = {
   __clerk_help: string;
 };
 
-export type VerificationStatus = 'expired' | 'failed' | 'loading' | 'verified' | 'verified_switch_tab';
+export type VerificationStatus =
+  | 'expired'
+  | 'failed'
+  | 'loading'
+  | 'verified'
+  | 'verified_switch_tab'
+  | 'client_mismatch';
 
 export function getClerkQueryParam<T extends ClerkQueryParam>(param: T): ClerkQueryParamsToValuesMap[T] | null {
   const val = new URL(window.location.href).searchParams.get(param);

packages/localizations/src/en-US.ts

@@ -325,6 +325,11 @@ export const enUS: LocalizationResource = {
         subtitleNewTab: 'Return to the newly opened tab to continue',
         titleNewTab: 'Signed in on other tab',
       },
+      clientMismatch: {
+        subtitle:
+          'To continue, open the verification link on the device and browser from which you initiated the sign-in',
+        title: 'Verification link is invalid for this device',
+      },
     },
     forgotPassword: {
       formTitle: 'Reset password code',
@@ -426,6 +431,11 @@ export const enUS: LocalizationResource = {
         subtitleNewTab: 'Return to previous tab to continue',
         title: 'Successfully verified email',
       },
+      clientMismatch: {
+        subtitle:
+          'To continue, open the verification link on the device and browser from which you initiated the sign-up',
+        title: 'Verification link is invalid for this device',
+      },
     },
     phoneCode: {
       formSubtitle: 'Enter the verification code sent to your phone number',

packages/shared/src/error.ts

@@ -188,6 +188,7 @@ export function isEmailLinkError(err: Error): err is EmailLinkError {
 export const EmailLinkErrorCode = {
   Expired: 'expired',
   Failed: 'failed',
+  ClientMismatch: 'client_mismatch',
 };
 
 const DefaultMessages = Object.freeze({

packages/types/src/localization.ts

@@ -117,6 +117,10 @@ type _LocalizationResource = {
         subtitle: LocalizationValue;
         subtitleNewTab: LocalizationValue;
       };
+      clientMismatch: {
+        title: LocalizationValue;
+        subtitle: LocalizationValue;
+      };
     };
     emailCode: {
       title: LocalizationValue;
@@ -221,6 +225,10 @@ type _LocalizationResource = {
         title: LocalizationValue;
         subtitle: LocalizationValue;
       };
+      clientMismatch: {
+        title: LocalizationValue;
+        subtitle: LocalizationValue;
+      };
     };
     phoneCode: {
       title: LocalizationValue;