fix(clerk-js,types): Correctly determine destination first factor (#6789)

Co-authored-by: Nikos Douvlis <[email protected]>

Author: dstaley

.changeset/ready-days-relax.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+[Experimental] Correctly determine destination first factor based on identifier.

packages/clerk-js/bundlewatch.config.json

@@ -1,9 +1,9 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "819KB" },
+    { "path": "./dist/clerk.js", "maxSize": "821KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "121KB" },
-    { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
+    { "path": "./dist/clerk.headless*.js", "maxSize": "63KB" },
     { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
     { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },
     { "path": "./dist/vendors*.js", "maxSize": "45KB" },

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

@@ -15,11 +15,14 @@ import type {
   AuthenticateWithWeb3Params,
   CreateEmailLinkFlowReturn,
   EmailCodeConfig,
+  EmailCodeFactor,
   EmailLinkConfig,
+  EmailLinkFactor,
   EnterpriseSSOConfig,
   PassKeyConfig,
   PasskeyFactor,
   PhoneCodeConfig,
+  PhoneCodeFactor,
   PrepareFirstFactorParams,
   PrepareSecondFactorParams,
   ResetPasswordEmailCodeFactorConfig,
@@ -544,6 +547,11 @@ export class SignIn extends BaseResource implements SignInResource {
   }
 }
 
+type SelectFirstFactorParams =
+  | { strategy: 'email_code'; emailAddressId?: string; phoneNumberId?: never }
+  | { strategy: 'email_link'; emailAddressId?: string; phoneNumberId?: never }
+  | { strategy: 'phone_code'; phoneNumberId?: string; emailAddressId?: never };
+
 class SignInFuture implements SignInFutureResource {
   emailCode = {
     sendCode: this.sendEmailCode.bind(this),
@@ -692,22 +700,32 @@ class SignInFuture implements SignInFutureResource {
     });
   }
 
-  async sendEmailCode(params: SignInFutureEmailCodeSendParams): Promise<{ error: unknown }> {
-    const { email } = params;
+  async sendEmailCode(params: SignInFutureEmailCodeSendParams = {}): Promise<{ error: unknown }> {
+    const { emailAddress, emailAddressId } = params;
+    if (!this.resource.id && emailAddressId) {
+      throw new Error(
+        'signIn.emailCode.sendCode() cannot be called with an emailAddressId if an existing signIn does not exist.',
+      );
+    }
+
+    if (!this.resource.id && !emailAddress) {
+      throw new Error(
+        'signIn.emailCode.sendCode() cannot be called without an emailAddress if an existing signIn does not exist.',
+      );
+    }
+
     return runAsyncResourceTask(this.resource, async () => {
-      if (!this.resource.id) {
-        await this.create({ identifier: email });
+      if (emailAddress) {
+        await this.create({ identifier: emailAddress });
       }
 
-      const emailCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_code');
-
+      const emailCodeFactor = this.selectFirstFactor({ strategy: 'email_code', emailAddressId });
       if (!emailCodeFactor) {
         throw new Error('Email code factor not found');
       }
 
-      const { emailAddressId } = emailCodeFactor;
       await this.resource.__internal_basePost({
-        body: { emailAddressId, strategy: 'email_code' },
+        body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
         action: 'prepare_first_factor',
       });
     });
@@ -724,20 +742,29 @@ class SignInFuture implements SignInFutureResource {
   }
 
   async sendEmailLink(params: SignInFutureEmailLinkSendParams): Promise<{ error: unknown }> {
-    const { email, verificationUrl } = params;
+    const { emailAddress, verificationUrl, emailAddressId } = params;
+    if (!this.resource.id && emailAddressId) {
+      throw new Error(
+        'signIn.emailLink.sendLink() cannot be called with an emailAddressId if an existing signIn does not exist.',
+      );
+    }
+
+    if (!this.resource.id && !emailAddress) {
+      throw new Error(
+        'signIn.emailLink.sendLink() cannot be called without an emailAddress if an existing signIn does not exist.',
+      );
+    }
+
     return runAsyncResourceTask(this.resource, async () => {
-      if (!this.resource.id) {
-        await this.create({ identifier: email });
+      if (emailAddress) {
+        await this.create({ identifier: emailAddress });
       }
 
-      const emailLinkFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_link');
-
+      const emailLinkFactor = this.selectFirstFactor({ strategy: 'email_link', emailAddressId });
       if (!emailLinkFactor) {
         throw new Error('Email link factor not found');
       }
 
-      const { emailAddressId } = emailLinkFactor;
-
       let absoluteVerificationUrl = verificationUrl;
       try {
         new URL(verificationUrl);
@@ -746,7 +773,11 @@ class SignInFuture implements SignInFutureResource {
       }
 
       await this.resource.__internal_basePost({
-        body: { emailAddressId, redirectUrl: absoluteVerificationUrl, strategy: 'email_link' },
+        body: {
+          emailAddressId: emailLinkFactor.emailAddressId,
+          redirectUrl: absoluteVerificationUrl,
+          strategy: 'email_link',
+        },
         action: 'prepare_first_factor',
       });
     });
@@ -773,22 +804,32 @@ class SignInFuture implements SignInFutureResource {
     });
   }
 
-  async sendPhoneCode(params: SignInFuturePhoneCodeSendParams): Promise<{ error: unknown }> {
-    const { phoneNumber, channel = 'sms' } = params;
+  async sendPhoneCode(params: SignInFuturePhoneCodeSendParams = {}): Promise<{ error: unknown }> {
+    const { phoneNumber, phoneNumberId, channel = 'sms' } = params;
+    if (!this.resource.id && phoneNumberId) {
+      throw new Error(
+        'signIn.phoneCode.sendCode() cannot be called with an phoneNumberId if an existing signIn does not exist.',
+      );
+    }
+
+    if (!this.resource.id && !phoneNumber) {
+      throw new Error(
+        'signIn.phoneCode.sendCode() cannot be called without an phoneNumber if an existing signIn does not exist.',
+      );
+    }
+
     return runAsyncResourceTask(this.resource, async () => {
-      if (!this.resource.id) {
+      if (phoneNumber) {
         await this.create({ identifier: phoneNumber });
       }
 
-      const phoneCodeFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'phone_code');
-
+      const phoneCodeFactor = this.selectFirstFactor({ strategy: 'phone_code', phoneNumberId });
       if (!phoneCodeFactor) {
         throw new Error('Phone code factor not found');
       }
 
-      const { phoneNumberId } = phoneCodeFactor;
       await this.resource.__internal_basePost({
-        body: { phoneNumberId, strategy: 'phone_code', channel },
+        body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
         action: 'prepare_first_factor',
       });
     });
@@ -886,4 +927,60 @@ class SignInFuture implements SignInFutureResource {
       await SignIn.clerk.setActive({ session: this.resource.createdSessionId, navigate });
     });
   }
+
+  private selectFirstFactor(
+    params: Extract<SelectFirstFactorParams, { strategy: 'email_code' }>,
+  ): EmailCodeFactor | null;
+  private selectFirstFactor(
+    params: Extract<SelectFirstFactorParams, { strategy: 'email_link' }>,
+  ): EmailLinkFactor | null;
+  private selectFirstFactor(
+    params: Extract<SelectFirstFactorParams, { strategy: 'phone_code' }>,
+  ): PhoneCodeFactor | null;
+  private selectFirstFactor({
+    strategy,
+    emailAddressId,
+    phoneNumberId,
+  }: SelectFirstFactorParams): EmailCodeFactor | EmailLinkFactor | PhoneCodeFactor | null {
+    if (!this.resource.supportedFirstFactors) {
+      return null;
+    }
+
+    if (emailAddressId) {
+      const factor = this.resource.supportedFirstFactors.find(
+        f => f.strategy === strategy && f.emailAddressId === emailAddressId,
+      ) as EmailCodeFactor | EmailLinkFactor;
+      if (factor) {
+        return factor;
+      }
+    }
+
+    if (phoneNumberId) {
+      const factor = this.resource.supportedFirstFactors.find(
+        f => f.strategy === strategy && f.phoneNumberId === phoneNumberId,
+      ) as PhoneCodeFactor;
+      if (factor) {
+        return factor;
+      }
+    }
+
+    // Try to find a factor that matches the identifier.
+    const factorForIdentifier = this.resource.supportedFirstFactors.find(
+      f => f.strategy === strategy && f.safeIdentifier === this.resource.identifier,
+    ) as EmailCodeFactor | EmailLinkFactor | PhoneCodeFactor;
+    if (factorForIdentifier) {
+      return factorForIdentifier;
+    }
+
+    // If no factor is found matching the identifier, try to find a factor that matches the strategy.
+    const factorForStrategy = this.resource.supportedFirstFactors.find(f => f.strategy === strategy) as
+      | EmailCodeFactor
+      | EmailLinkFactor
+      | PhoneCodeFactor;
+    if (factorForStrategy) {
+      return factorForStrategy;
+    }
+
+    return null;
+  }
 }

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

@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { BaseResource } from '../internal';
+import { SignIn } from '../SignIn';
+
+describe('SignIn', () => {
+  describe('SignInFuture', () => {
+    describe('selectFirstFactor', () => {
+      const signInCreatedJSON = {
+        id: 'test_id',
+
+        supported_first_factors: [
+          { strategy: 'email_code', emailAddressId: 'email_address_0', safe_identifier: '[email protected]' },
+          { strategy: 'email_code', emailAddressId: 'email_address_1', safe_identifier: '[email protected]' },
+          { strategy: 'phone_code', phoneNumberId: 'phone_number_1', safe_identifier: '+301234567890' },
+        ],
+      };
+
+      const firstFactorPreparedJSON = {};
+
+      BaseResource._fetch = vi.fn().mockImplementation(({ method, path, body }) => {
+        if (method === 'POST' && path === '/client/sign_ins') {
+          return Promise.resolve({
+            client: null,
+            response: { ...signInCreatedJSON, identifier: body.identifier },
+          });
+        }
+
+        if (method === 'POST' && path === '/client/sign_ins/test_id/prepare_first_factor') {
+          return Promise.resolve({
+            client: null,
+            response: firstFactorPreparedJSON,
+          });
+        }
+
+        throw new Error('Unexpected call to BaseResource._fetch');
+      });
+
+      it('should select correct first factor by email address', async () => {
+        const signIn = new SignIn();
+        await signIn.__internal_future.emailCode.sendCode({ emailAddress: '[email protected]' });
+        expect(BaseResource._fetch).toHaveBeenLastCalledWith({
+          method: 'POST',
+          path: '/client/sign_ins/test_id/prepare_first_factor',
+          body: {
+            emailAddressId: 'email_address_1',
+            strategy: 'email_code',
+          },
+        });
+      });
+
+      it('should select correct first factor by email address ID', async () => {
+        const signIn = new SignIn();
+        await signIn.__internal_future.create({ identifier: '[email protected]' });
+        await signIn.__internal_future.emailCode.sendCode({ emailAddressId: 'email_address_1' });
+        expect(BaseResource._fetch).toHaveBeenLastCalledWith({
+          method: 'POST',
+          path: '/client/sign_ins/test_id/prepare_first_factor',
+          body: {
+            emailAddressId: 'email_address_1',
+            strategy: 'email_code',
+          },
+        });
+      });
+
+      it('should select correct first factor matching identifier when nothing is provided', async () => {
+        const signIn = new SignIn();
+        await signIn.__internal_future.create({ identifier: '[email protected]' });
+        await signIn.__internal_future.emailCode.sendCode();
+        expect(BaseResource._fetch).toHaveBeenLastCalledWith({
+          method: 'POST',
+          path: '/client/sign_ins/test_id/prepare_first_factor',
+          body: {
+            emailAddressId: 'email_address_1',
+            strategy: 'email_code',
+          },
+        });
+      });
+
+      it('should select correct first factor when nothing is provided', async () => {
+        const signIn = new SignIn();
+        await signIn.__internal_future.create({ identifier: '+12255550000' });
+        await signIn.__internal_future.emailCode.sendCode();
+        expect(BaseResource._fetch).toHaveBeenLastCalledWith({
+          method: 'POST',
+          path: '/client/sign_ins/test_id/prepare_first_factor',
+          body: {
+            emailAddressId: 'email_address_0',
+            strategy: 'email_code',
+          },
+        });
+      });
+    });
+  });
+});

packages/types/src/signInFuture.ts

@@ -38,14 +38,27 @@ export type SignInFuturePasswordParams =
       email?: never;
     };
 
-export interface SignInFutureEmailCodeSendParams {
-  email: string;
-}
+export type SignInFutureEmailCodeSendParams =
+  | {
+      emailAddress?: string;
+      emailAddressId?: never;
+    }
+  | {
+      emailAddressId?: string;
+      emailAddress?: never;
+    };
 
-export interface SignInFutureEmailLinkSendParams {
-  email: string;
-  verificationUrl: string;
-}
+export type SignInFutureEmailLinkSendParams =
+  | {
+      emailAddress?: string;
+      verificationUrl: string;
+      emailAddressId?: never;
+    }
+  | {
+      emailAddressId?: string;
+      verificationUrl: string;
+      emailAddress?: never;
+    };
 
 export interface SignInFutureEmailCodeVerifyParams {
   code: string;
@@ -56,10 +69,17 @@ export interface SignInFutureResetPasswordSubmitParams {
   signOutOfOtherSessions?: boolean;
 }
 
-export interface SignInFuturePhoneCodeSendParams {
-  phoneNumber?: string;
-  channel?: PhoneCodeChannel;
-}
+export type SignInFuturePhoneCodeSendParams =
+  | {
+      phoneNumber?: string;
+      channel?: PhoneCodeChannel;
+      phoneNumberId?: never;
+    }
+  | {
+      phoneNumberId: string;
+      channel?: PhoneCodeChannel;
+      phoneNumber?: never;
+    };
 
 export interface SignInFuturePhoneCodeVerifyParams {
   code: string;