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

.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;
+ };
+
  /**
  *
  */

.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;
+ };
+
  /**
  *
  */

.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;
+ };
+
  /**
  *
  */

.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;
+ };
+
  /**
  *
  */

.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;
+ };
+
  /**
  *
  */

.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;
+ };
+
  /**
  *
  */

.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;
+ };
+
  /**
  *
  */

.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;
+ };
+
  /**
  *
  */