feat(clerk-js,clerk-react,types): Signal email link sign in support (#6766)

Author: dstaley

.changeset/free-rockets-flow.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/clerk-react': minor
+'@clerk/types': minor
+---
+
+[Experimental] Signal email link support

packages/clerk-js/bundlewatch.config.json

@@ -2,7 +2,7 @@
   "files": [
     { "path": "./dist/clerk.js", "maxSize": "819KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "79KB" },
-    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "120.2KB" },
+    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "121KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
     { "path": "./dist/ui-common*.js", "maxSize": "117.1KB" },
     { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "120KB" },

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

@@ -1,3 +1,4 @@
+import { inBrowser } from '@clerk/shared/browser';
 import { ClerkWebAuthnError } from '@clerk/shared/error';
 import { Poller } from '@clerk/shared/poller';
 import { deepCamelToSnake, deepSnakeToCamel } from '@clerk/shared/underscore';
@@ -31,6 +32,7 @@ import type {
   SignInFutureCreateParams,
   SignInFutureEmailCodeSendParams,
   SignInFutureEmailCodeVerifyParams,
+  SignInFutureEmailLinkSendParams,
   SignInFutureFinalizeParams,
   SignInFutureMFAPhoneCodeVerifyParams,
   SignInFuturePasswordParams,
@@ -61,6 +63,7 @@ import {
   generateSignatureWithMetamask,
   generateSignatureWithOKXWallet,
   getBaseIdentifier,
+  getClerkQueryParam,
   getCoinbaseWalletIdentifier,
   getMetamaskIdentifier,
   getOKXWalletIdentifier,
@@ -140,6 +143,14 @@ export class SignIn extends BaseResource implements SignInResource {
    */
   __internal_basePost = this._basePost.bind(this);
 
+  /**
+   * @internal Only used for internal purposes, and is not intended to be used directly.
+   *
+   * This property is used to provide access to underlying Client methods to `SignInFuture`, which wraps an instance
+   * of `SignIn`.
+   */
+  __internal_baseGet = this._baseGet.bind(this);
+
   constructor(data: SignInJSON | SignInJSONSnapshot | null = null) {
     super();
     this.fromJSON(data);
@@ -539,6 +550,34 @@ class SignInFuture implements SignInFutureResource {
     verifyCode: this.verifyEmailCode.bind(this),
   };
 
+  emailLink = {
+    sendLink: this.sendEmailLink.bind(this),
+    waitForVerification: this.waitForEmailLinkVerification.bind(this),
+    get verification() {
+      if (!inBrowser()) {
+        return null;
+      }
+
+      const status = getClerkQueryParam('__clerk_status') as 'verified' | 'expired' | 'failed' | 'client_mismatch';
+      const createdSessionId = getClerkQueryParam('__clerk_created_session');
+
+      if (!status || !createdSessionId) {
+        return null;
+      }
+
+      const verifiedFromTheSameClient =
+        status === 'verified' &&
+        typeof SignIn.clerk.client !== 'undefined' &&
+        SignIn.clerk.client.sessions.some(s => s.id === createdSessionId);
+
+      return {
+        status,
+        createdSessionId,
+        verifiedFromTheSameClient,
+      };
+    },
+  };
+
   resetPasswordEmailCode = {
     sendCode: this.sendResetPasswordEmailCode.bind(this),
     verifyCode: this.verifyResetPasswordEmailCode.bind(this),
@@ -583,6 +622,10 @@ class SignInFuture implements SignInFutureResource {
     return undefined;
   }
 
+  get firstFactorVerification() {
+    return this.resource.firstFactorVerification;
+  }
+
   async sendResetPasswordEmailCode(): Promise<{ error: unknown }> {
     return runAsyncResourceTask(this.resource, async () => {
       if (!this.resource.id) {
@@ -680,6 +723,56 @@ class SignInFuture implements SignInFutureResource {
     });
   }
 
+  async sendEmailLink(params: SignInFutureEmailLinkSendParams): Promise<{ error: unknown }> {
+    const { email, verificationUrl } = params;
+    return runAsyncResourceTask(this.resource, async () => {
+      if (!this.resource.id) {
+        await this.create({ identifier: email });
+      }
+
+      const emailLinkFactor = this.resource.supportedFirstFactors?.find(f => f.strategy === 'email_link');
+
+      if (!emailLinkFactor) {
+        throw new Error('Email link factor not found');
+      }
+
+      const { emailAddressId } = emailLinkFactor;
+
+      let absoluteVerificationUrl = verificationUrl;
+      try {
+        new URL(verificationUrl);
+      } catch {
+        absoluteVerificationUrl = window.location.origin + verificationUrl;
+      }
+
+      await this.resource.__internal_basePost({
+        body: { emailAddressId, redirectUrl: absoluteVerificationUrl, strategy: 'email_link' },
+        action: 'prepare_first_factor',
+      });
+    });
+  }
+
+  async waitForEmailLinkVerification(): Promise<{ error: unknown }> {
+    return runAsyncResourceTask(this.resource, async () => {
+      const { run, stop } = Poller();
+      await new Promise((resolve, reject) => {
+        void run(async () => {
+          try {
+            const res = await this.resource.__internal_baseGet();
+            const status = res.firstFactorVerification.status;
+            if (status === 'verified' || status === 'expired') {
+              stop();
+              resolve(res);
+            }
+          } catch (err) {
+            stop();
+            reject(err);
+          }
+        });
+      });
+    });
+  }
+
   async sendPhoneCode(params: SignInFuturePhoneCodeSendParams): Promise<{ error: unknown }> {
     const { phoneNumber, channel = 'sms' } = params;
     return runAsyncResourceTask(this.resource, async () => {
@@ -787,6 +880,9 @@ class SignInFuture implements SignInFutureResource {
         throw new Error('Cannot finalize sign-in without a created session.');
       }
 
+      // Reload the client to prevent an issue where the created session is not picked up.
+      await SignIn.clerk.client?.reload();
+
       await SignIn.clerk.setActive({ session: this.resource.createdSessionId, navigate });
     });
   }

packages/react/src/stateProxy.ts

@@ -35,6 +35,7 @@ export class StateProxy implements State {
   }
 
   private buildSignInProxy() {
+    const gateProperty = this.gateProperty.bind(this);
     const target = () => this.client.signIn.__internal_future;
 
     return {
@@ -44,13 +45,40 @@ export class StateProxy implements State {
         status: 'needs_identifier' as const,
         availableStrategies: [],
         isTransferable: false,
+        get firstFactorVerification() {
+          return gateProperty(target, 'firstFactorVerification', {
+            status: null,
+            error: null,
+            expireAt: null,
+            externalVerificationRedirectURL: null,
+            nonce: null,
+            attempts: null,
+            message: null,
+            strategy: null,
+            verifiedAtClient: null,
+            verifiedFromTheSameClient: () => false,
+            __internal_toSnapshot: () => {
+              throw new Error('__internal_toSnapshot called before Clerk is loaded');
+            },
+            pathRoot: '',
+            reload: () => {
+              throw new Error('__internal_toSnapshot called before Clerk is loaded');
+            },
+          });
+        },
 
         create: this.gateMethod(target, 'create'),
         password: this.gateMethod(target, 'password'),
         sso: this.gateMethod(target, 'sso'),
         finalize: this.gateMethod(target, 'finalize'),
 
         emailCode: this.wrapMethods(() => target().emailCode, ['sendCode', 'verifyCode'] as const),
+        emailLink: this.wrapStruct(
+          () => target().emailLink,
+          ['sendLink', 'waitForVerification'] as const,
+          ['verification'] as const,
+          { verification: null },
+        ),
         resetPasswordEmailCode: this.wrapMethods(() => target().resetPasswordEmailCode, [
           'sendCode',
           'verifyCode',
@@ -148,4 +176,27 @@ export class StateProxy implements State {
   ): Pick<T, K[number]> {
     return Object.fromEntries(keys.map(k => [k, this.gateMethod(getTarget, k)])) as Pick<T, K[number]>;
   }
+
+  private wrapStruct<T extends object, M extends readonly (keyof T)[], G extends readonly (keyof T)[]>(
+    getTarget: () => T,
+    methods: M,
+    getters: G,
+    fallbacks: Pick<T, G[number]>,
+  ): Pick<T, M[number] | G[number]> & {
+    [K in M[number]]: T[K] extends (...args: any[]) => any ? T[K] : never;
+  } & {
+    [K in G[number]]: T[K] extends (...args: any[]) => any ? never : T[K];
+  } {
+    const out: any = {};
+    for (const m of methods) {
+      out[m] = this.gateMethod(getTarget, m as any);
+    }
+    for (const g of getters) {
+      Object.defineProperty(out, g, {
+        get: () => this.gateProperty(getTarget, g as any, (fallbacks as any)[g]),
+        enumerable: true,
+      });
+    }
+    return out;
+  }
 }

packages/types/src/signInFuture.ts

@@ -2,6 +2,7 @@ import type { SetActiveNavigate } from './clerk';
 import type { PhoneCodeChannel } from './phoneCodeChannel';
 import type { SignInFirstFactor, SignInStatus } from './signInCommon';
 import type { OAuthStrategy } from './strategies';
+import type { VerificationResource } from './verification';
 
 export interface SignInFutureCreateParams {
   identifier?: string;
@@ -41,6 +42,11 @@ export interface SignInFutureEmailCodeSendParams {
   email: string;
 }
 
+export interface SignInFutureEmailLinkSendParams {
+  email: string;
+  verificationUrl: string;
+}
+
 export interface SignInFutureEmailCodeVerifyParams {
   code: string;
 }
@@ -111,6 +117,8 @@ export interface SignInFutureResource {
 
   readonly existingSession?: { sessionId: string };
 
+  readonly firstFactorVerification: VerificationResource;
+
   /**
    * Used to supply an identifier for the sign-in attempt. Calling this method will populate data on the sign-in
    * attempt, such as `signIn.resource.supportedFirstFactors`.
@@ -137,6 +145,41 @@ export interface SignInFutureResource {
     verifyCode: (params: SignInFutureEmailCodeVerifyParams) => Promise<{ error: unknown }>;
   };
 
+  /**
+   *
+   */
+  emailLink: {
+    /**
+     * Used to send an email link to sign-in
+     */
+    sendLink: (params: SignInFutureEmailLinkSendParams) => Promise<{ error: unknown }>;
+
+    /**
+     * Will wait for verification to complete or expire
+     */
+    waitForVerification: () => Promise<{ error: unknown }>;
+
+    /**
+     * The verification status
+     */
+    verification: {
+      /**
+       * The verification status
+       */
+      status: 'verified' | 'expired' | 'failed' | 'client_mismatch';
+
+      /**
+       * The created session ID
+       */
+      createdSessionId: string;
+
+      /**
+       * Whether the verification was from the same client
+       */
+      verifiedFromTheSameClient: boolean;
+    } | null;
+  };
+
   /**
    *
    */