feat(clerk-js): Introduce WhatsApp as an alternative phone code provider

.changeset/cold-pianos-return.md

@@ -0,0 +1,10 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/localizations': patch
+'@clerk/types': patch
+---
+
+Introduce `WhatsApp` as an alternative channel for phone code delivery.
+
+The new `channel` property accompanies the `phone_code` strategy. Possible values: `whatsapp` and `sms`.

packages/clerk-js/bundlewatch.config.json

@@ -1,10 +1,10 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "594.2kB" },
-    { "path": "./dist/clerk.browser.js", "maxSize": "68.3KB" },
+    { "path": "./dist/clerk.js", "maxSize": "595.5kB" },
+    { "path": "./dist/clerk.browser.js", "maxSize": "68.5KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "110KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "52KB" },
-    { "path": "./dist/ui-common*.js", "maxSize": "104.4KB" },
+    { "path": "./dist/ui-common*.js", "maxSize": "105KB" },
     { "path": "./dist/vendors*.js", "maxSize": "39.5KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
     { "path": "./dist/createorganization*.js", "maxSize": "5KB" },
@@ -13,7 +13,7 @@
     { "path": "./dist/organizationswitcher*.js", "maxSize": "5KB" },
     { "path": "./dist/organizationlist*.js", "maxSize": "5.5KB" },
     { "path": "./dist/signin*.js", "maxSize": "14KB" },
-    { "path": "./dist/#*.js", "maxSize": "6.76KB" },
+    { "path": "./dist/#*.js", "maxSize": "7.5KB" },
     { "path": "./dist/userbutton*.js", "maxSize": "5KB" },
     { "path": "./dist/userprofile*.js", "maxSize": "16.5KB" },
     { "path": "./dist/userverification*.js", "maxSize": "5KB" },

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

@@ -120,6 +120,7 @@ export class SignIn extends BaseResource implements SignInResource {
         config = {
           phoneNumberId: factor.phoneNumberId,
           default: factor.default,
+          channel: factor.channel,
         } as PhoneCodeConfig;
         break;
       case 'web3_metamask_signature':

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

@@ -5,6 +5,7 @@ import type {
   OAuthStrategy,
   PasskeySettingsData,
   PasswordSettingsData,
+  PhoneCodeChannel,
   SamlSettings,
   SignInData,
   #Data,
@@ -173,6 +174,17 @@ export class UserSettings extends BaseResource implements UserSettingsResource {
       .flat() as any as Web3Strategy[];
   }
 
+  get alternativePhoneCodeChannels(): PhoneCodeChannel[] {
+    if (!this.attributes) {
+      return [];
+    }
+
+    return Object.entries(this.attributes)
+      .filter(([name, attr]) => attr.used_for_first_factor && name === 'phone_number')
+      .map(([, desc]) => desc?.channels?.filter(factor => factor !== 'sms') || [])
+      .flat() as any as PhoneCodeChannel[];
+  }
+
   public constructor(data: UserSettingsJSON | UserSettingsJSONSnapshot | null = null) {
     super();
     this.fromJSON(data);

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

@@ -2,6 +2,7 @@ import { errorToJSON, parseError } from '@clerk/shared/error';
 import type {
   ClerkAPIError,
   PasskeyVerificationResource,
+  PhoneCodeChannel,
   PublicKeyCredentialCreationOptionsJSON,
   PublicKeyCredentialCreationOptionsWithoutExtensions,
   #VerificationJSON,
@@ -32,6 +33,7 @@ export class Verification extends BaseResource implements VerificationResource {
   expireAt: Date | null = null;
   error: ClerkAPIError | null = null;
   verifiedAtClient: string | null = null;
+  channel?: PhoneCodeChannel;
 
   constructor(data: VerificationJSON | VerificationJSONSnapshot | null) {
     super();
@@ -57,6 +59,7 @@ export class Verification extends BaseResource implements VerificationResource {
       this.attempts = data.attempts;
       this.expireAt = unixEpochToDate(data.expire_at || undefined);
       this.error = data.error ? parseError(data.error) : null;
+      this.channel = data.channel || undefined;
     }
     return this;
   }

packages/clerk-js/src/core/resources/__tests__/__snapshots__/Client.test.ts.snap

@@ -229,6 +229,7 @@ Client {
     "createdSessionId": null,
     "firstFactorVerification": Verification {
       "attempts": null,
+      "channel": undefined,
       "error": {
         "code": "",
         "longMessage": undefined,
@@ -259,6 +260,7 @@ Client {
     "resetPassword": [Function],
     "secondFactorVerification": Verification {
       "attempts": null,
+      "channel": undefined,
       "error": {
         "code": "",
         "longMessage": undefined,
@@ -335,6 +337,7 @@ Client {
     "verifications": #Verifications {
       "emailAddress": #Verification {
         "attempts": null,
+        "channel": undefined,
         "error": {
           "code": "",
           "longMessage": undefined,
@@ -361,6 +364,7 @@ Client {
       },
       "externalAccount": Verification {
         "attempts": null,
+        "channel": undefined,
         "error": {
           "code": "",
           "longMessage": undefined,
@@ -385,6 +389,7 @@ Client {
       },
       "phoneNumber": #Verification {
         "attempts": null,
+        "channel": undefined,
         "error": {
           "code": "",
           "longMessage": undefined,
@@ -411,6 +416,7 @@ Client {
       },
       "web3Wallet": #Verification {
         "attempts": null,
+        "channel": undefined,
         "error": {
           "code": "",
           "longMessage": undefined,

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

@@ -1,12 +1,12 @@
-import type { OAuthProvider, Web3Provider } from '@clerk/types';
+import type { OAuthProvider, PhoneCodeProvider, Web3Provider } from '@clerk/types';
 
 import { Box, descriptors, Text } from '../customizables';
 import type { PropsOfComponent } from '../styledSystem';
 import { common } from '../styledSystem';
 
 type ProviderInitialIconProps = PropsOfComponent<typeof Box> & {
   value: string;
-  id: Web3Provider | OAuthProvider;
+  id: Web3Provider | OAuthProvider | PhoneCodeProvider;
 };
 
 export const ProviderInitialIcon = (props: ProviderInitialIconProps) => {

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

@@ -85,6 +85,7 @@ const AlternativeMethodsList = (props: AlternativeMethodListProps) => {
                   <SignInSocialButtons
                     enableWeb3Providers
                     enableOAuthProviders
+                    enableAlternativePhoneCodeProviders={false}
                   />
                   {firstPartyFactors &&
                     firstPartyFactors.map((factor, i) => (

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

@@ -0,0 +1,102 @@
+import type { PhoneCodeChannelData } from '@clerk/types';
+
+import { Button, Col, descriptors, Flex, Image, localizationKeys } from '../../customizables';
+import { Card, Form, Header, useCardState } from '../../elements';
+import { CaptchaElement } from '../../elements/CaptchaElement';
+import { useEnabledThirdPartyProviders } from '../../hooks';
+import type { FormControlState } from '../../utils';
+
+type #AlternativePhoneCodePhoneNumberCardProps = {
+  handleSubmit: React.FormEventHandler;
+  phoneNumberFormState: FormControlState<any>;
+  onUseAnotherMethod: () => void;
+  phoneCodeProvider: PhoneCodeChannelData;
+};
+
+export const SignInAlternativePhoneCodePhoneNumberCard = (props: #AlternativePhoneCodePhoneNumberCardProps) => {
+  const { handleSubmit, phoneNumberFormState, onUseAnotherMethod, phoneCodeProvider } = props;
+  const { providerToDisplayData, strategyToDisplayData } = useEnabledThirdPartyProviders();
+  const provider = phoneCodeProvider.name;
+  const channel = phoneCodeProvider.channel;
+  const card = useCardState();
+
+  return (
+    <Card.Root>
+      <Card.Content>
+        <Header.Root
+          showLogo
+          showDivider
+        >
+          <Col center>
+            <Image
+              src={providerToDisplayData[channel]?.iconUrl}
+              alt={`${strategyToDisplayData[channel].name} logo`}
+              sx={theme => ({
+                width: theme.sizes.$7,
+                height: theme.sizes.$7,
+                maxWidth: '100%',
+                marginBottom: theme.sizes.$6,
+              })}
+            />
+          </Col>
+          <Header.Title
+            localizationKey={localizationKeys('signIn.start.alternativePhoneCodeProvider.title', {
+              provider,
+            })}
+          />
+          <Header.Subtitle
+            localizationKey={localizationKeys('signIn.start.alternativePhoneCodeProvider.subtitle', {
+              provider,
+            })}
+          />
+        </Header.Root>
+        <Card.Alert>{card.error}</Card.Alert>
+        <Flex
+          direction='col'
+          elementDescriptor={descriptors.main}
+          gap={6}
+        >
+          <Form.Root
+            onSubmit={handleSubmit}
+            gap={8}
+          >
+            <Col gap={6}>
+              <Form.ControlRow elementId='phoneNumber'>
+                <Form.PhoneInput
+                  {...phoneNumberFormState.props}
+                  label={localizationKeys('signIn.start.alternativePhoneCodeProvider.label', { provider })}
+                  isRequired
+                  isOptional={false}
+                  actionLabel={undefined}
+                  onActionClicked={undefined}
+                />
+              </Form.ControlRow>
+            </Col>
+            <Col center>
+              <CaptchaElement />
+              <Col
+                gap={6}
+                sx={{
+                  width: '100%',
+                }}
+              >
+                <Form.SubmitButton
+                  hasArrow
+                  localizationKey={localizationKeys('formButtonPrimary')}
+                />
+              </Col>
+            </Col>
+            <Col center>
+              <Button
+                variant='link'
+                colorScheme='neutral'
+                onClick={onUseAnotherMethod}
+                localizationKey={localizationKeys('signIn.start.alternativePhoneCodeProvider.actionLink')}
+              />
+            </Col>
+          </Form.Root>
+        </Flex>
+      </Card.Content>
+    </Card.Root>
+  );
+};

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

@@ -37,7 +37,9 @@ function SignInFactorOneInternal(): JSX.Element {
   const availableFactors = signIn.supportedFirstFactors;
   const router = useRouter();
   const card = useCardState();
-  const { supportedFirstFactors } = useCoreSignIn();
+  const { supportedFirstFactors, firstFactorVerification } = useCoreSignIn();
+
+  const alternativePhoneCodeChannel = firstFactorVerification.channel;
 
   const lastPreparedFactorKeyRef = React.useRef('');
   const [{ currentFactor }, setFactor] = React.useState<{
@@ -157,7 +159,7 @@ function SignInFactorOneInternal(): JSX.Element {
         <SignInFactorOnePhoneCodeCard
           factorAlreadyPrepared={lastPreparedFactorKeyRef.current === factorKey(currentFactor)}
           onFactorPrepare={handleFactorPrepare}
-          factor={currentFactor}
+          factor={{ ...currentFactor, channel: alternativePhoneCodeChannel }}
           onShowAlternativeMethodsClicked={toggleAllStrategies}
         />
       );

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

@@ -38,6 +38,8 @@ export const SignInFactorOneCodeForm = (props: SignInFactorOneCodeFormProps) =>
   const clerk = useClerk();
 
   const shouldAvoidPrepare = signIn.firstFactorVerification.status === 'verified' && props.factorAlreadyPrepared;
+  const isAlternativePhoneCodeProvider =
+    props.factor.strategy === 'phone_code' ? !!props.factor.channel && props.factor.channel !== 'sms' : false;
 
   const goBack = () => {
     return navigate('../');
@@ -55,7 +57,9 @@ export const SignInFactorOneCodeForm = (props: SignInFactorOneCodeFormProps) =>
   };
 
   useFetch(
-    shouldAvoidPrepare
+    // If an alternative phone code provider is used, we skip the prepare step
+    // because the verification is already created on the Start screen
+    shouldAvoidPrepare || isAlternativePhoneCodeProvider
       ? undefined
       : () =>
           signIn
@@ -109,7 +113,9 @@ export const SignInFactorOneCodeForm = (props: SignInFactorOneCodeFormProps) =>
       onResendCodeClicked={prepare}
       safeIdentifier={props.factor.safeIdentifier}
       profileImageUrl={signIn.userData.imageUrl}
-      onShowAlternativeMethodsClicked={props.onShowAlternativeMethodsClicked}
+      // if the factor is an alternative phone code provider, we don't want to show the alternative methods
+      // instead we want to go back to the start screen
+      onShowAlternativeMethodsClicked={isAlternativePhoneCodeProvider ? goBack : props.onShowAlternativeMethodsClicked}
       showAlternativeMethods={props.showAlternativeMethods}
       onIdentityPreviewEditClicked={goBack}
       onBackLinkClicked={props.onBackLinkClicked}

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

@@ -1,23 +1,37 @@
+import { getAlternativePhoneCodeProviderData } from '@clerk/shared/alternativePhoneCode';
 import type { PhoneCodeFactor } from '@clerk/types';
 
-import { useEnvironment } from '../../contexts';
 import { Flow, localizationKeys } from '../../customizables';
 import type { SignInFactorOneCodeCard } from './SignInFactorOneCodeForm';
 import { SignInFactorOneCodeForm } from './SignInFactorOneCodeForm';
 
 type SignInFactorOnePhoneCodeCardProps = SignInFactorOneCodeCard & { factor: PhoneCodeFactor };
 
 export const SignInFactorOnePhoneCodeCard = (props: SignInFactorOnePhoneCodeCardProps) => {
-  const { applicationName } = useEnvironment().displayConfig;
+  const { factor } = props;
+  const { channel } = factor;
+
+  let cardTitle = localizationKeys('signIn.phoneCode.title');
+  let cardSubtitle = localizationKeys('signIn.phoneCode.subtitle');
+  let inputLabel = localizationKeys('signIn.phoneCode.formTitle');
+  let resendButton = localizationKeys('signIn.phoneCode.resendButton');
+  if (channel && channel !== 'sms') {
+    cardTitle = localizationKeys('signIn.alternativePhoneCodeProvider.title', {
+      provider: getAlternativePhoneCodeProviderData(channel)?.name,
+    });
+    cardSubtitle = localizationKeys('signIn.alternativePhoneCodeProvider.subtitle');
+    inputLabel = localizationKeys('signIn.alternativePhoneCodeProvider.formTitle');
+    resendButton = localizationKeys('signIn.alternativePhoneCodeProvider.resendButton');
+  }
 
   return (
     <Flow.Part part='phoneCode'>
       <SignInFactorOneCodeForm
         {...props}
-        cardTitle={localizationKeys('signIn.phoneCode.title')}
-        cardSubtitle={localizationKeys('signIn.phoneCode.subtitle', { applicationName })}
-        inputLabel={localizationKeys('signIn.phoneCode.formTitle')}
-        resendButton={localizationKeys('signIn.phoneCode.resendButton')}
+        cardTitle={cardTitle}
+        cardSubtitle={cardSubtitle}
+        inputLabel={inputLabel}
+        resendButton={resendButton}
       />
     </Flow.Part>
   );