chore(*): Rename refs of MagicLink to EmailLink - deprecation JS Docs (…

…#1833)

* chore(types): Add new types and deprecation JSDoc for renaming MagicLink to EmailLink

* chore(shared): Add deprecation JSDoc for renaming *MagicLink* to *EmailLink*

* chore(clerk-js): Drop MagicLink refs and use EmailLink in /ui

Since the /ui is internal it is safe to use the EmailLink
references instead of the EmailLink.

* chore(clerk-js): Add deprecation JSDoc for renaming *MagicLink* to *EmailLink*

* chore(clerk-react): Add deprecation JSDoc for renaming *MagicLink* to *EmailLink*

* chore(clerk-expo): Re-export modules for renaming *MagicLink* to *EmailLink*

* chore(nextjs): Re-export new modules for renaming *MagicLink* to *EmailLink*

* chore(chrome-extension): Fix chrome-extension snapshot tests caused by re-export

* chore(repo): Add changeset

.changeset/tricky-olives-rescue.md

@@ -0,0 +1,12 @@
+---
+'@clerk/chrome-extension': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+'@clerk/clerk-expo': patch
+---
+
+Introduce new `*EmailLink*` helpers that will replace the `*MagicLink*` helpers.
+Also marked all the `*MagicLink*` as deprecated using JSDocs.

packages/chrome-extension/src/__snapshots__/exports.test.ts.snap

@@ -7,6 +7,7 @@ exports[`public exports should not include a breaking change 1`] = `
   "ClerkLoading",
   "ClerkProvider",
   "CreateOrganization",
+  "EmailLinkErrorCode",
   "MagicLinkErrorCode",
   "MultisessionAppSupport",
   "OrganizationList",
@@ -32,11 +33,13 @@ exports[`public exports should not include a breaking change 1`] = `
   "WithUser",
   "__internal__setErrorThrowerOptions",
   "isClerkAPIResponseError",
+  "isEmailLinkError",
   "isKnownError",
   "isMagicLinkError",
   "isMetamaskError",
   "useAuth",
   "useClerk",
+  "useEmailLink",
   "useMagicLink",
   "useOrganization",
   "useOrganizationList",

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

@@ -5,7 +5,7 @@ import { mockNativeRuntime } from '../testUtils';
 import Clerk from './clerk';
 import { eventBus, events } from './events';
 import type { AuthConfig, DisplayConfig, Organization } from './resources/internal';
-import { Client, Environment, MagicLinkErrorCode, SignIn, SignUp } from './resources/internal';
+import { Client, EmailLinkErrorCode, Environment, MagicLinkErrorCode, SignIn, SignUp } from './resources/internal';
 import { SessionCookieService } from './services';
 import { mockJwt } from './test/fixtures';
 
@@ -1355,6 +1355,7 @@ describe('Clerk singleton', () => {
     });
   });
 
+  // deprecated: Will be replaced by handleEmailLinkVerification
   describe('.handleMagicLinkVerification()', () => {
     beforeEach(() => {
       mockClientFetch.mockReset();
@@ -1616,6 +1617,267 @@ describe('Clerk singleton', () => {
     });
   });
 
+  describe('.handleEmailLinkVerification()', () => {
+    beforeEach(() => {
+      mockClientFetch.mockReset();
+      mockEnvironmentFetch.mockReset();
+    });
+
+    it('completes the sign in flow if a session was created on this client', async () => {
+      const createdSessionId = 'sess_123';
+      setWindowQueryParams([
+        ['__clerk_status', 'verified'],
+        ['__clerk_created_session', createdSessionId],
+      ]);
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          activeSessions: [],
+          sessions: [{ id: createdSessionId }],
+          signIn: new SignIn({
+            status: 'completed',
+          } as any as SignInJSON),
+          signUp: new SignUp(null),
+        }),
+      );
+      const mockSetActive = jest.fn();
+
+      const sut = new Clerk(frontendApi);
+      await sut.load({
+        navigate: mockNavigate,
+      });
+      sut.setActive = mockSetActive;
+
+      const redirectUrlComplete = '/redirect-to';
+      sut.handleEmailLinkVerification({ redirectUrlComplete });
+
+      await waitFor(() => {
+        expect(mockSetActive).toHaveBeenCalledWith({
+          session: createdSessionId,
+          beforeEmit: expect.any(Function),
+        });
+      });
+    });
+
+    it("continues to redirectUrl for sign in that's not completed", async () => {
+      setWindowQueryParams([['__clerk_status', 'verified']]);
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          activeSessions: [],
+          sessions: [],
+          signIn: new SignIn({
+            status: 'needs_second_factor',
+          } as any as SignInJSON),
+          signUp: new SignUp(null),
+        }),
+      );
+      const mockSetActive = jest.fn();
+
+      const sut = new Clerk(frontendApi);
+      await sut.load({
+        navigate: mockNavigate,
+      });
+      sut.setActive = mockSetActive;
+
+      const redirectUrl = '/2fa';
+      sut.handleEmailLinkVerification({ redirectUrl });
+
+      await waitFor(() => {
+        expect(mockSetActive).not.toHaveBeenCalled();
+        expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+      });
+    });
+
+    it('completes the sign up flow if a session was created on this client', async () => {
+      const createdSessionId = 'sess_123';
+      setWindowQueryParams([
+        ['__clerk_status', 'verified'],
+        ['__clerk_created_session', createdSessionId],
+      ]);
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          activeSessions: [],
+          sessions: [{ id: createdSessionId }],
+          signUp: new SignUp({
+            status: 'completed',
+          } as any as SignUpJSON),
+          signIn: new SignIn(null),
+        }),
+      );
+      const mockSetActive = jest.fn();
+
+      const sut = new Clerk(frontendApi);
+      await sut.load({
+        navigate: mockNavigate,
+      });
+      sut.setActive = mockSetActive;
+
+      const redirectUrlComplete = '/redirect-to';
+      sut.handleEmailLinkVerification({ redirectUrlComplete });
+
+      await waitFor(() => {
+        expect(mockSetActive).toHaveBeenCalledWith({
+          session: createdSessionId,
+          beforeEmit: expect.any(Function),
+        });
+      });
+    });
+
+    it("continues the sign up flow for a sign up that's not completed", async () => {
+      setWindowQueryParams([['__clerk_status', 'verified']]);
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          activeSessions: [],
+          sessions: [],
+          signUp: new SignUp({
+            status: 'missing_requirements',
+          } as any as SignUpJSON),
+          signIn: new SignIn(null),
+        }),
+      );
+      const mockSetActive = jest.fn();
+
+      const sut = new Clerk(frontendApi);
+      await sut.load({
+        navigate: mockNavigate,
+      });
+      sut.setActive = mockSetActive;
+
+      const redirectUrl = '/next-up';
+      sut.handleEmailLinkVerification({ redirectUrl });
+
+      await waitFor(() => {
+        expect(mockSetActive).not.toHaveBeenCalled();
+        expect(mockNavigate).toHaveBeenCalledWith(redirectUrl);
+      });
+    });
+
+    it('throws an error for expired verification status parameter', async () => {
+      setWindowQueryParams([['__clerk_status', 'expired']]);
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          activeSessions: [],
+          sessions: [],
+          signUp: new SignUp(null),
+          signIn: new SignIn(null),
+        }),
+      );
+      const mockSetActive = jest.fn();
+
+      const sut = new Clerk(frontendApi);
+      await sut.load({
+        navigate: mockNavigate,
+      });
+      sut.setActive = mockSetActive;
+
+      await expect(async () => {
+        await sut.handleEmailLinkVerification({});
+      }).rejects.toThrow(EmailLinkErrorCode.Expired);
+      expect(mockSetActive).not.toHaveBeenCalled();
+    });
+
+    it('throws an error for failed verification status parameter', async () => {
+      setWindowQueryParams([['__clerk_status', 'failed']]);
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          activeSessions: [],
+          sessions: [],
+          signUp: new SignUp(null),
+          signIn: new SignIn(null),
+        }),
+      );
+      const mockSetActive = jest.fn();
+
+      const sut = new Clerk(frontendApi);
+      await sut.load({
+        navigate: mockNavigate,
+      });
+      sut.setActive = mockSetActive;
+
+      await expect(async () => {
+        await sut.handleEmailLinkVerification({});
+      }).rejects.toThrow(EmailLinkErrorCode.Failed);
+      expect(mockSetActive).not.toHaveBeenCalled();
+    });
+
+    it('runs a callback when verified on other device', async () => {
+      setWindowQueryParams([
+        ['__clerk_status', 'verified'],
+        ['__clerk_created_session', 'sess_123'],
+      ]);
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          activeSessions: [],
+          sessions: [],
+          signUp: new SignUp(null),
+          signIn: new SignIn(null),
+        }),
+      );
+      const mockSetActive = jest.fn();
+      const sut = new Clerk(frontendApi);
+      await sut.load({
+        navigate: mockNavigate,
+      });
+      sut.setActive = mockSetActive;
+      const res = { ping: 'ping' };
+      const cb = () => {
+        res.ping = 'pong';
+      };
+      await sut.handleEmailLinkVerification({ onVerifiedOnOtherDevice: cb });
+      expect(res.ping).toEqual('pong');
+      expect(mockSetActive).not.toHaveBeenCalled();
+    });
+
+    it('throws an error with no status query parameter', async () => {
+      setWindowQueryParams([['__clerk_created_session', 'sess_123']]);
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          activeSessions: [],
+          sessions: [],
+          signUp: new SignUp(null),
+          signIn: new SignIn(null),
+        }),
+      );
+      const mockSetActive = jest.fn();
+      const sut = new Clerk(frontendApi);
+      await sut.load({
+        navigate: mockNavigate,
+      });
+      sut.setActive = mockSetActive;
+      await expect(async () => {
+        await sut.handleEmailLinkVerification({});
+      }).rejects.toThrow(EmailLinkErrorCode.Failed);
+      expect(mockSetActive).not.toHaveBeenCalled();
+    });
+
+    it('throws an error for invalid status query parameter', async () => {
+      setWindowQueryParams([
+        ['__clerk_status', 'whatever'],
+        ['__clerk_created_session', 'sess_123'],
+      ]);
+      mockClientFetch.mockReturnValue(
+        Promise.resolve({
+          activeSessions: [],
+          sessions: [{ id: 'sess_123' }],
+          signIn: new SignIn({
+            status: 'completed',
+          } as any as SignInJSON),
+          signUp: new SignUp(null),
+        }),
+      );
+      const mockSetActive = jest.fn();
+      const sut = new Clerk(frontendApi);
+      await sut.load({
+        navigate: mockNavigate,
+      });
+      sut.setActive = mockSetActive;
+
+      await expect(async () => {
+        await sut.handleEmailLinkVerification({});
+      }).rejects.toThrow(EmailLinkErrorCode.Failed);
+      expect(mockSetActive).not.toHaveBeenCalled();
+    });
+  });
+
   /**
    * TODO:
    * 1) Write better test names for this.domain and this.isSatellite

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

@@ -27,6 +27,7 @@ import type {
   DomainOrProxyUrl,
   EnvironmentJSON,
   EnvironmentResource,
+  HandleEmailLinkVerificationParams,
   HandleMagicLinkVerificationParams,
   HandleOAuthCallbackParams,
   InstanceType,
@@ -104,6 +105,8 @@ import createFapiClient from './fapiClient';
 import {
   BaseResource,
   Client,
+  EmailLinkError,
+  EmailLinkErrorCode,
   Environment,
   MagicLinkError,
   MagicLinkErrorCode,
@@ -809,6 +812,10 @@ export default class Clerk implements ClerkInterface {
     return;
   };
 
+  /**
+   *
+   * @deprecated Use `handleEmailLinkVerification` instead.
+   */
   public handleMagicLinkVerification = async (
     params: HandleMagicLinkVerificationParams,
     customNavigate?: (to: string) => Promise<unknown>,
@@ -852,6 +859,49 @@ export default class Clerk implements ClerkInterface {
     return null;
   };
 
+  public handleEmailLinkVerification = async (
+    params: HandleEmailLinkVerificationParams,
+    customNavigate?: (to: string) => Promise<unknown>,
+  ): Promise<unknown> => {
+    if (!this.client) {
+      return;
+    }
+
+    const verificationStatus = getClerkQueryParam('__clerk_status');
+    if (verificationStatus === 'expired') {
+      throw new EmailLinkError(EmailLinkErrorCode.Expired);
+    } else if (verificationStatus !== 'verified') {
+      throw new EmailLinkError(EmailLinkErrorCode.Failed);
+    }
+
+    const newSessionId = getClerkQueryParam('__clerk_created_session');
+    const { signIn, signUp, sessions } = this.client;
+
+    const shouldCompleteOnThisDevice = sessions.some(s => s.id === newSessionId);
+    const shouldContinueOnThisDevice =
+      signIn.status === 'needs_second_factor' || signUp.status === 'missing_requirements';
+
+    const navigate = (to: string) =>
+      customNavigate && typeof customNavigate === 'function' ? customNavigate(to) : this.navigate(to);
+
+    const redirectComplete = params.redirectUrlComplete ? () => navigate(params.redirectUrlComplete as string) : noop;
+    const redirectContinue = params.redirectUrl ? () => navigate(params.redirectUrl as string) : noop;
+
+    if (shouldCompleteOnThisDevice) {
+      return this.setActive({
+        session: newSessionId,
+        beforeEmit: redirectComplete,
+      });
+    } else if (shouldContinueOnThisDevice) {
+      return redirectContinue();
+    }
+
+    if (typeof params.onVerifiedOnOtherDevice === 'function') {
+      params.onVerifiedOnOtherDevice();
+    }
+    return null;
+  };
+
   public handleRedirectCallback = async (
     params: HandleOAuthCallbackParams = {},
     customNavigate?: (to: string) => Promise<unknown>,