chore(clerk-js,types,localizations): Improve error handling when web3 wallet is not installed (#4845)

Author: nikospapcom

.changeset/nasty-adults-shave.md

@@ -0,0 +1,7 @@
+---
+'@clerk/localizations': patch
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Improve error handling when trying to sign-in/sign-up with web3 wallet and wallet is not installed in the browser 

packages/clerk-js/src/ui/components/SignIn/SignInSocialButtons.tsx

@@ -8,7 +8,7 @@ import { useCardState } from '../../elements/contexts';
 import type { SocialButtonsProps } from '../../elements/SocialButtons';
 import { SocialButtons } from '../../elements/SocialButtons';
 import { useRouter } from '../../router';
-import { handleError } from '../../utils';
+import { handleError, web3CallbackErrorHandler } from '../../utils';
 
 export const SignInSocialButtons = React.memo((props: SocialButtonsProps) => {
   const clerk = useClerk();
@@ -36,7 +36,7 @@ export const SignInSocialButtons = React.memo((props: SocialButtonsProps) => {
             signUpContinueUrl: ctx.signUpContinueUrl,
             strategy,
           })
-          .catch(err => handleError(err, [], card.setError));
+          .catch(err => web3CallbackErrorHandler(err, card.setError));
       }}
     />
   );

packages/clerk-js/src/ui/components/SignUp/SignUpSocialButtons.tsx

@@ -7,7 +7,7 @@ import { useCardState } from '../../elements';
 import type { SocialButtonsProps } from '../../elements/SocialButtons';
 import { SocialButtons } from '../../elements/SocialButtons';
 import { useRouter } from '../../router';
-import { handleError } from '../../utils';
+import { handleError, web3CallbackErrorHandler } from '../../utils';
 
 export type SignUpSocialButtonsProps = SocialButtonsProps & { continueSignUp?: boolean; legalAccepted?: boolean };
 
@@ -46,7 +46,7 @@ export const SignUpSocialButtons = React.memo((props: SignUpSocialButtonsProps)
             strategy,
             legalAccepted: props.legalAccepted,
           })
-          .catch(err => handleError(err, [], card.setError));
+          .catch(err => web3CallbackErrorHandler(err, card.setError));
       }}
     />
   );

packages/clerk-js/src/ui/utils/index.ts

@@ -24,3 +24,4 @@ export * from './ExternalElementMounter';
 export * from './colorOptionToHslaScale';
 export * from './createCustomMenuItems';
 export * from './usernameUtils';
+export * from './web3CallbackErrorHandler';

packages/clerk-js/src/ui/utils/web3CallbackErrorHandler.ts

@@ -0,0 +1,23 @@
+import { ClerkRuntimeError, isClerkAPIResponseError } from '@clerk/shared/error';
+import type { ClerkAPIError, ClerkRuntimeError as ClerkRuntimeErrorType } from '@clerk/types';
+
+import { handleError } from './errorHandler';
+
+type Web3CallbackErrorHandler = {
+  (err: any, setError?: (err: ClerkRuntimeErrorType | ClerkAPIError | string | undefined) => void): void;
+};
+
+export const web3CallbackErrorHandler: Web3CallbackErrorHandler = (err, setError) => {
+  if (
+    isClerkAPIResponseError(err) &&
+    err.errors[0].meta?.paramName === 'identifier' &&
+    err.errors[0].code === 'form_param_nil'
+  ) {
+    const error = new ClerkRuntimeError('A Web3 Wallet extension cannot be found. Please install one to continue.', {
+      code: 'web3_missing_identifier',
+    });
+
+    return handleError(error, [], setError);
+  }
+  return handleError(err, [], setError);
+};

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

@@ -10,6 +10,8 @@ type GetWeb3IdentifierParams = {
 export async function getWeb3Identifier(params: GetWeb3IdentifierParams): Promise<string> {
   const { provider } = params;
   const ethereum = await getEthereumProvider(provider);
+
+  // TODO - core-3: Improve error handling for the case when the provider is not found
   if (!ethereum) {
     // If a plugin for the requested provider is not found,
     // the flow will fail as it has been the expected behavior so far.
@@ -28,6 +30,8 @@ type GenerateWeb3SignatureParams = GenerateSignatureParams & {
 export async function generateWeb3Signature(params: GenerateWeb3SignatureParams): Promise<string> {
   const { identifier, nonce, provider } = params;
   const ethereum = await getEthereumProvider(provider);
+
+  // TODO - core-3: Improve error handling for the case when the provider is not found
   if (!ethereum) {
     // If a plugin for the requested provider is not found,
     // the flow will fail as it has been the expected behavior so far.

packages/localizations/src/en-US.ts

@@ -582,6 +582,7 @@ export const enUS: LocalizationResource = {
     passkey_pa_not_supported: 'Registration requires a platform authenticator but the device does not support it.',
     passkey_registration_cancelled: 'Passkey registration was cancelled or timed out.',
     passkey_retrieval_cancelled: 'Passkey verification was cancelled or timed out.',
+    web3_missing_identifier: 'A Web3 Wallet extension cannot be found. Please install one to continue.',
     passwordComplexity: {
       maximumLength: 'less than {{length}} characters',
       minimumLength: '{{length}} or more characters',

packages/types/src/localization.ts

@@ -835,6 +835,7 @@ type UnstableErrors = WithParamName<{
   passkey_retrieval_cancelled: LocalizationValue;
   passkey_registration_cancelled: LocalizationValue;
   passkey_already_exists: LocalizationValue;
+  web3_missing_identifier: LocalizationValue;
   form_password_pwned: LocalizationValue;
   form_password_pwned__sign_in: LocalizationValue;
   form_username_invalid_length: LocalizationValue;