fix(js): Coalesce concurrent first/second factor preparations

.changeset/calm-codes-share.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-js": patch
+---
+
+Prevent overlapping verification preparations from triggering duplicate verification sends during sign-in, sign-up, and when verifying an email address, phone number, or web3 wallet from the user profile.

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

@@ -25,8 +25,18 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
 export type BaseMutateParams = {
  action?: string;
  body?: any;
+ coalesce?: boolean;
  method?: HTTPMethod;
  path?: string;
+ signal?: AbortSignal;
+};
+
+const COALESCED_POST_TTL_MS = 30_000;
+
+type PendingCoalescedPost<T> = {
+ promise: Promise<T>;
+ controller: AbortController;
+ expiresAt: number;
 };
 
 function assertProductionKeysOnDev(statusCode: number, payloadErrors?: ClerkAPIErrorJSON[]) {
@@ -58,6 +68,8 @@ export abstract class BaseResource {
  id?: string;
  pathRoot = '';
 
+ #pendingCoalescedPosts?: Map<string, PendingCoalescedPost<this>>;
+
  static get fapiClient(): FapiClient {
  return BaseResource.clerk.getFapiClient();
  }
@@ -217,9 +229,9 @@ export abstract class BaseResource {
  }
 
  protected async _baseMutate<J extends ClerkResourceJSON | null>(params: BaseMutateParams): Promise<this> {
- const { action, body, method, path } = params;
+ const { action, body, method, path, signal } = params;
  // TODO @userland-errors:
- const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body });
+ const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body, signal });
  return this.fromJSON((json?.response || json) as J);
  }
 
@@ -230,7 +242,32 @@ export abstract class BaseResource {
  }
 
  protected async _basePost<J extends ClerkResourceJSON | null>(params: BaseMutateParams = {}): Promise<this> {
- return this._baseMutate<J>({ ...params, method: 'POST' });
+ if (!params.coalesce) {
+ return this._baseMutate<J>({ ...params, method: 'POST' });
+ }
+
+ const key = this.#coalescedPostKey(params);
+ const posts = (this.#pendingCoalescedPosts ??= new Map());
+ const pending = posts.get(key);
+ if (pending && Date.now() < pending.expiresAt) {
+ return pending.promise;
+ }
+
+ const controller = new AbortController();
+ const promise = this._baseMutate<J>({ ...params, method: 'POST', signal: controller.signal }).finally(() => {
+ if (posts.get(key)?.promise === promise) {
+ posts.delete(key);
+ }
+ });
+ posts.set(key, { promise, controller, expiresAt: Date.now() + COALESCED_POST_TTL_MS });
+ return promise;
+ }
+
+ #coalescedPostKey(params: BaseMutateParams): string {
+ const body = Object.entries(params.body ?? {})
+ .filter(([, value]) => value !== undefined)
+ .sort(([left], [right]) => (left < right ? -1 : 1));
+ return JSON.stringify([this.id, params.path, params.action, body]);
  }
 
  protected async _basePostBypass<J extends ClerkResourceJSON>(params: BaseMutateParams = {}): Promise<this> {

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

@@ -38,6 +38,7 @@ export class EmailAddress extends BaseResource implements EmailAddressResource {
  prepareVerification = (params: PrepareEmailAddressVerificationParams): Promise<this> => {
  return this._basePost<EmailAddressJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

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

@@ -34,6 +34,7 @@ export class PhoneNumber extends BaseResource implements PhoneNumberResource {
  prepareVerification = (): Promise<PhoneNumberResource> => {
  return this._basePost<PhoneNumberJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { strategy: 'phone_code' },
  });
  };

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

@@ -265,6 +265,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: { ...config, strategy: params.strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  };
 
@@ -356,6 +357,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: params,
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  };
 
@@ -883,6 +885,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'reset_password_email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -926,6 +929,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'reset_password_phone_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1083,6 +1087,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1135,6 +1140,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'email_link',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1187,6 +1193,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1252,6 +1259,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'enterprise_sso',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1319,6 +1327,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { web3WalletId: web3FirstFactor.web3WalletId, strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
 
  const { message } = this.firstFactorVerification;
@@ -1390,6 +1399,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'passkey' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1442,6 +1452,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'phone_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }
@@ -1468,6 +1479,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'email_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }

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

@@ -188,6 +188,7 @@ export class SignUp extends BaseResource implements SignUpResource {
  return this._basePost({
  body: params,
  action: 'prepare_verification',
+ coalesce: true,
  });
  };
 
@@ -973,6 +974,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_code' },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -993,6 +995,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'phone_code', channel },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1020,6 +1023,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_link', redirectUrl: absoluteVerificationUrl },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1163,6 +1167,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy },
  action: 'prepare_verification',
+ coalesce: true,
  });
 
  const { message } = this.#resource.verifications.web3Wallet;

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

@@ -30,6 +30,7 @@ export class Web3Wallet extends BaseResource implements Web3WalletResource {
  prepareVerification = (params: PrepareWeb3WalletVerificationParams): Promise<this> => {
  return this._basePost<Web3WalletJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

packages/clerk-js/src/core/resources/__tests__/EmailAddress.test.ts

@@ -0,0 +1,123 @@
+import type { EmailAddressJSON } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, EmailAddress } from '../internal';
+
+describe('EmailAddress', () => {
+ describe('prepareVerification', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('coalesces concurrent identical preparations', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = emailAddress.prepareVerification(params);
+ const second = emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce preparations with different strategies or params', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+
+ await Promise.all([
+ emailAddress.prepareVerification({ strategy: 'email_code' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-one' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-two' }),
+ ]);
+
+ expect(mockFetch).toHaveBeenCalledTimes(3);
+ });
+
+ it('starts a new preparation after the previous request succeeds', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await emailAddress.prepareVerification(params);
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('starts a new preparation after the previous request fails', async () => {
+ const mockFetch = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('prepare failed'))
+ .mockResolvedValueOnce({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await expect(emailAddress.prepareVerification(params)).rejects.toThrow('prepare failed');
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not coalesce preparations across EmailAddress instances', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const firstEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const secondEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = firstEmailAddress.prepareVerification(params);
+ const second = secondEmailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce concurrent verification attempts', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { code: '123456' };
+
+ const first = emailAddress.attemptVerification(params);
+ const second = emailAddress.attemptVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+ });
+});

.changeset/calm-codes-share.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-js": patch
+---
+
+Prevent overlapping verification preparations from triggering duplicate verification sends during sign-in, sign-up, and when verifying an email address, phone number, or web3 wallet from the user profile.

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

@@ -25,8 +25,18 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
 export type BaseMutateParams = {
  action?: string;
  body?: any;
+ coalesce?: boolean;
  method?: HTTPMethod;
  path?: string;
+ signal?: AbortSignal;
+};
+
+const COALESCED_POST_TTL_MS = 30_000;
+
+type PendingCoalescedPost<T> = {
+ promise: Promise<T>;
+ controller: AbortController;
+ expiresAt: number;
 };
 
 function assertProductionKeysOnDev(statusCode: number, payloadErrors?: ClerkAPIErrorJSON[]) {
@@ -58,6 +68,8 @@ export abstract class BaseResource {
  id?: string;
  pathRoot = '';
 
+ #pendingCoalescedPosts?: Map<string, PendingCoalescedPost<this>>;
+
  static get fapiClient(): FapiClient {
  return BaseResource.clerk.getFapiClient();
  }
@@ -217,9 +229,9 @@ export abstract class BaseResource {
  }
 
  protected async _baseMutate<J extends ClerkResourceJSON | null>(params: BaseMutateParams): Promise<this> {
- const { action, body, method, path } = params;
+ const { action, body, method, path, signal } = params;
  // TODO @userland-errors:
- const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body });
+ const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body, signal });
  return this.fromJSON((json?.response || json) as J);
  }
 
@@ -230,7 +242,32 @@ export abstract class BaseResource {
  }
 
  protected async _basePost<J extends ClerkResourceJSON | null>(params: BaseMutateParams = {}): Promise<this> {
- return this._baseMutate<J>({ ...params, method: 'POST' });
+ if (!params.coalesce) {
+ return this._baseMutate<J>({ ...params, method: 'POST' });
+ }
+
+ const key = this.#coalescedPostKey(params);
+ const posts = (this.#pendingCoalescedPosts ??= new Map());
+ const pending = posts.get(key);
+ if (pending && Date.now() < pending.expiresAt) {
+ return pending.promise;
+ }
+
+ const controller = new AbortController();
+ const promise = this._baseMutate<J>({ ...params, method: 'POST', signal: controller.signal }).finally(() => {
+ if (posts.get(key)?.promise === promise) {
+ posts.delete(key);
+ }
+ });
+ posts.set(key, { promise, controller, expiresAt: Date.now() + COALESCED_POST_TTL_MS });
+ return promise;
+ }
+
+ #coalescedPostKey(params: BaseMutateParams): string {
+ const body = Object.entries(params.body ?? {})
+ .filter(([, value]) => value !== undefined)
+ .sort(([left], [right]) => (left < right ? -1 : 1));
+ return JSON.stringify([this.id, params.path, params.action, body]);
  }
 
  protected async _basePostBypass<J extends ClerkResourceJSON>(params: BaseMutateParams = {}): Promise<this> {

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

@@ -38,6 +38,7 @@ export class EmailAddress extends BaseResource implements EmailAddressResource {
  prepareVerification = (params: PrepareEmailAddressVerificationParams): Promise<this> => {
  return this._basePost<EmailAddressJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

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

@@ -34,6 +34,7 @@ export class PhoneNumber extends BaseResource implements PhoneNumberResource {
  prepareVerification = (): Promise<PhoneNumberResource> => {
  return this._basePost<PhoneNumberJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { strategy: 'phone_code' },
  });
  };

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

@@ -265,6 +265,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: { ...config, strategy: params.strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  };
 
@@ -356,6 +357,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: params,
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  };
 
@@ -883,6 +885,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'reset_password_email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -926,6 +929,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'reset_password_phone_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1083,6 +1087,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1135,6 +1140,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'email_link',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1187,6 +1193,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1252,6 +1259,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'enterprise_sso',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1319,6 +1327,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { web3WalletId: web3FirstFactor.web3WalletId, strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
 
  const { message } = this.firstFactorVerification;
@@ -1390,6 +1399,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'passkey' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1442,6 +1452,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'phone_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }
@@ -1468,6 +1479,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'email_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }

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

@@ -188,6 +188,7 @@ export class SignUp extends BaseResource implements SignUpResource {
  return this._basePost({
  body: params,
  action: 'prepare_verification',
+ coalesce: true,
  });
  };
 
@@ -973,6 +974,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_code' },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -993,6 +995,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'phone_code', channel },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1020,6 +1023,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_link', redirectUrl: absoluteVerificationUrl },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1163,6 +1167,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy },
  action: 'prepare_verification',
+ coalesce: true,
  });
 
  const { message } = this.#resource.verifications.web3Wallet;

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

@@ -30,6 +30,7 @@ export class Web3Wallet extends BaseResource implements Web3WalletResource {
  prepareVerification = (params: PrepareWeb3WalletVerificationParams): Promise<this> => {
  return this._basePost<Web3WalletJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

packages/clerk-js/src/core/resources/__tests__/EmailAddress.test.ts

@@ -0,0 +1,123 @@
+import type { EmailAddressJSON } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, EmailAddress } from '../internal';
+
+describe('EmailAddress', () => {
+ describe('prepareVerification', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('coalesces concurrent identical preparations', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = emailAddress.prepareVerification(params);
+ const second = emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce preparations with different strategies or params', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+
+ await Promise.all([
+ emailAddress.prepareVerification({ strategy: 'email_code' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-one' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-two' }),
+ ]);
+
+ expect(mockFetch).toHaveBeenCalledTimes(3);
+ });
+
+ it('starts a new preparation after the previous request succeeds', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await emailAddress.prepareVerification(params);
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('starts a new preparation after the previous request fails', async () => {
+ const mockFetch = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('prepare failed'))
+ .mockResolvedValueOnce({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await expect(emailAddress.prepareVerification(params)).rejects.toThrow('prepare failed');
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not coalesce preparations across EmailAddress instances', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const firstEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const secondEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = firstEmailAddress.prepareVerification(params);
+ const second = secondEmailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce concurrent verification attempts', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { code: '123456' };
+
+ const first = emailAddress.attemptVerification(params);
+ const second = emailAddress.attemptVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+ });
+});

.changeset/calm-codes-share.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-js": patch
+---
+
+Prevent overlapping verification preparations from triggering duplicate verification sends during sign-in, sign-up, and when verifying an email address, phone number, or web3 wallet from the user profile.

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

@@ -25,8 +25,18 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
 export type BaseMutateParams = {
  action?: string;
  body?: any;
+ coalesce?: boolean;
  method?: HTTPMethod;
  path?: string;
+ signal?: AbortSignal;
+};
+
+const COALESCED_POST_TTL_MS = 30_000;
+
+type PendingCoalescedPost<T> = {
+ promise: Promise<T>;
+ controller: AbortController;
+ expiresAt: number;
 };
 
 function assertProductionKeysOnDev(statusCode: number, payloadErrors?: ClerkAPIErrorJSON[]) {
@@ -58,6 +68,8 @@ export abstract class BaseResource {
  id?: string;
  pathRoot = '';
 
+ #pendingCoalescedPosts?: Map<string, PendingCoalescedPost<this>>;
+
  static get fapiClient(): FapiClient {
  return BaseResource.clerk.getFapiClient();
  }
@@ -217,9 +229,9 @@ export abstract class BaseResource {
  }
 
  protected async _baseMutate<J extends ClerkResourceJSON | null>(params: BaseMutateParams): Promise<this> {
- const { action, body, method, path } = params;
+ const { action, body, method, path, signal } = params;
  // TODO @userland-errors:
- const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body });
+ const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body, signal });
  return this.fromJSON((json?.response || json) as J);
  }
 
@@ -230,7 +242,32 @@ export abstract class BaseResource {
  }
 
  protected async _basePost<J extends ClerkResourceJSON | null>(params: BaseMutateParams = {}): Promise<this> {
- return this._baseMutate<J>({ ...params, method: 'POST' });
+ if (!params.coalesce) {
+ return this._baseMutate<J>({ ...params, method: 'POST' });
+ }
+
+ const key = this.#coalescedPostKey(params);
+ const posts = (this.#pendingCoalescedPosts ??= new Map());
+ const pending = posts.get(key);
+ if (pending && Date.now() < pending.expiresAt) {
+ return pending.promise;
+ }
+
+ const controller = new AbortController();
+ const promise = this._baseMutate<J>({ ...params, method: 'POST', signal: controller.signal }).finally(() => {
+ if (posts.get(key)?.promise === promise) {
+ posts.delete(key);
+ }
+ });
+ posts.set(key, { promise, controller, expiresAt: Date.now() + COALESCED_POST_TTL_MS });
+ return promise;
+ }
+
+ #coalescedPostKey(params: BaseMutateParams): string {
+ const body = Object.entries(params.body ?? {})
+ .filter(([, value]) => value !== undefined)
+ .sort(([left], [right]) => (left < right ? -1 : 1));
+ return JSON.stringify([this.id, params.path, params.action, body]);
  }
 
  protected async _basePostBypass<J extends ClerkResourceJSON>(params: BaseMutateParams = {}): Promise<this> {

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

@@ -38,6 +38,7 @@ export class EmailAddress extends BaseResource implements EmailAddressResource {
  prepareVerification = (params: PrepareEmailAddressVerificationParams): Promise<this> => {
  return this._basePost<EmailAddressJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

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

@@ -34,6 +34,7 @@ export class PhoneNumber extends BaseResource implements PhoneNumberResource {
  prepareVerification = (): Promise<PhoneNumberResource> => {
  return this._basePost<PhoneNumberJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { strategy: 'phone_code' },
  });
  };

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

@@ -265,6 +265,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: { ...config, strategy: params.strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  };
 
@@ -356,6 +357,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: params,
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  };
 
@@ -883,6 +885,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'reset_password_email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -926,6 +929,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'reset_password_phone_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1083,6 +1087,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1135,6 +1140,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'email_link',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1187,6 +1193,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1252,6 +1259,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'enterprise_sso',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1319,6 +1327,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { web3WalletId: web3FirstFactor.web3WalletId, strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
 
  const { message } = this.firstFactorVerification;
@@ -1390,6 +1399,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'passkey' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1442,6 +1452,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'phone_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }
@@ -1468,6 +1479,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'email_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }

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

@@ -188,6 +188,7 @@ export class SignUp extends BaseResource implements SignUpResource {
  return this._basePost({
  body: params,
  action: 'prepare_verification',
+ coalesce: true,
  });
  };
 
@@ -973,6 +974,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_code' },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -993,6 +995,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'phone_code', channel },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1020,6 +1023,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_link', redirectUrl: absoluteVerificationUrl },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1163,6 +1167,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy },
  action: 'prepare_verification',
+ coalesce: true,
  });
 
  const { message } = this.#resource.verifications.web3Wallet;

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

@@ -30,6 +30,7 @@ export class Web3Wallet extends BaseResource implements Web3WalletResource {
  prepareVerification = (params: PrepareWeb3WalletVerificationParams): Promise<this> => {
  return this._basePost<Web3WalletJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

packages/clerk-js/src/core/resources/__tests__/EmailAddress.test.ts

@@ -0,0 +1,123 @@
+import type { EmailAddressJSON } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, EmailAddress } from '../internal';
+
+describe('EmailAddress', () => {
+ describe('prepareVerification', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('coalesces concurrent identical preparations', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = emailAddress.prepareVerification(params);
+ const second = emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce preparations with different strategies or params', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+
+ await Promise.all([
+ emailAddress.prepareVerification({ strategy: 'email_code' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-one' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-two' }),
+ ]);
+
+ expect(mockFetch).toHaveBeenCalledTimes(3);
+ });
+
+ it('starts a new preparation after the previous request succeeds', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await emailAddress.prepareVerification(params);
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('starts a new preparation after the previous request fails', async () => {
+ const mockFetch = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('prepare failed'))
+ .mockResolvedValueOnce({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await expect(emailAddress.prepareVerification(params)).rejects.toThrow('prepare failed');
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not coalesce preparations across EmailAddress instances', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const firstEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const secondEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = firstEmailAddress.prepareVerification(params);
+ const second = secondEmailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce concurrent verification attempts', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { code: '123456' };
+
+ const first = emailAddress.attemptVerification(params);
+ const second = emailAddress.attemptVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+ });
+});

.changeset/calm-codes-share.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-js": patch
+---
+
+Prevent overlapping verification preparations from triggering duplicate verification sends during sign-in, sign-up, and when verifying an email address, phone number, or web3 wallet from the user profile.

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

@@ -25,8 +25,18 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
 export type BaseMutateParams = {
  action?: string;
  body?: any;
+ coalesce?: boolean;
  method?: HTTPMethod;
  path?: string;
+ signal?: AbortSignal;
+};
+
+const COALESCED_POST_TTL_MS = 30_000;
+
+type PendingCoalescedPost<T> = {
+ promise: Promise<T>;
+ controller: AbortController;
+ expiresAt: number;
 };
 
 function assertProductionKeysOnDev(statusCode: number, payloadErrors?: ClerkAPIErrorJSON[]) {
@@ -58,6 +68,8 @@ export abstract class BaseResource {
  id?: string;
  pathRoot = '';
 
+ #pendingCoalescedPosts?: Map<string, PendingCoalescedPost<this>>;
+
  static get fapiClient(): FapiClient {
  return BaseResource.clerk.getFapiClient();
  }
@@ -217,9 +229,9 @@ export abstract class BaseResource {
  }
 
  protected async _baseMutate<J extends ClerkResourceJSON | null>(params: BaseMutateParams): Promise<this> {
- const { action, body, method, path } = params;
+ const { action, body, method, path, signal } = params;
  // TODO @userland-errors:
- const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body });
+ const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body, signal });
  return this.fromJSON((json?.response || json) as J);
  }
 
@@ -230,7 +242,32 @@ export abstract class BaseResource {
  }
 
  protected async _basePost<J extends ClerkResourceJSON | null>(params: BaseMutateParams = {}): Promise<this> {
- return this._baseMutate<J>({ ...params, method: 'POST' });
+ if (!params.coalesce) {
+ return this._baseMutate<J>({ ...params, method: 'POST' });
+ }
+
+ const key = this.#coalescedPostKey(params);
+ const posts = (this.#pendingCoalescedPosts ??= new Map());
+ const pending = posts.get(key);
+ if (pending && Date.now() < pending.expiresAt) {
+ return pending.promise;
+ }
+
+ const controller = new AbortController();
+ const promise = this._baseMutate<J>({ ...params, method: 'POST', signal: controller.signal }).finally(() => {
+ if (posts.get(key)?.promise === promise) {
+ posts.delete(key);
+ }
+ });
+ posts.set(key, { promise, controller, expiresAt: Date.now() + COALESCED_POST_TTL_MS });
+ return promise;
+ }
+
+ #coalescedPostKey(params: BaseMutateParams): string {
+ const body = Object.entries(params.body ?? {})
+ .filter(([, value]) => value !== undefined)
+ .sort(([left], [right]) => (left < right ? -1 : 1));
+ return JSON.stringify([this.id, params.path, params.action, body]);
  }
 
  protected async _basePostBypass<J extends ClerkResourceJSON>(params: BaseMutateParams = {}): Promise<this> {

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

@@ -38,6 +38,7 @@ export class EmailAddress extends BaseResource implements EmailAddressResource {
  prepareVerification = (params: PrepareEmailAddressVerificationParams): Promise<this> => {
  return this._basePost<EmailAddressJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

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

@@ -34,6 +34,7 @@ export class PhoneNumber extends BaseResource implements PhoneNumberResource {
  prepareVerification = (): Promise<PhoneNumberResource> => {
  return this._basePost<PhoneNumberJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { strategy: 'phone_code' },
  });
  };

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

@@ -265,6 +265,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: { ...config, strategy: params.strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  };
 
@@ -356,6 +357,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: params,
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  };
 
@@ -883,6 +885,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'reset_password_email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -926,6 +929,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'reset_password_phone_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1083,6 +1087,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1135,6 +1140,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'email_link',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1187,6 +1193,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1252,6 +1259,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'enterprise_sso',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1319,6 +1327,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { web3WalletId: web3FirstFactor.web3WalletId, strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
 
  const { message } = this.firstFactorVerification;
@@ -1390,6 +1399,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'passkey' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1442,6 +1452,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'phone_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }
@@ -1468,6 +1479,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'email_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }

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

@@ -188,6 +188,7 @@ export class SignUp extends BaseResource implements SignUpResource {
  return this._basePost({
  body: params,
  action: 'prepare_verification',
+ coalesce: true,
  });
  };
 
@@ -973,6 +974,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_code' },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -993,6 +995,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'phone_code', channel },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1020,6 +1023,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_link', redirectUrl: absoluteVerificationUrl },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1163,6 +1167,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy },
  action: 'prepare_verification',
+ coalesce: true,
  });
 
  const { message } = this.#resource.verifications.web3Wallet;

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

@@ -30,6 +30,7 @@ export class Web3Wallet extends BaseResource implements Web3WalletResource {
  prepareVerification = (params: PrepareWeb3WalletVerificationParams): Promise<this> => {
  return this._basePost<Web3WalletJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

packages/clerk-js/src/core/resources/__tests__/EmailAddress.test.ts

@@ -0,0 +1,123 @@
+import type { EmailAddressJSON } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, EmailAddress } from '../internal';
+
+describe('EmailAddress', () => {
+ describe('prepareVerification', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('coalesces concurrent identical preparations', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = emailAddress.prepareVerification(params);
+ const second = emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce preparations with different strategies or params', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+
+ await Promise.all([
+ emailAddress.prepareVerification({ strategy: 'email_code' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-one' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-two' }),
+ ]);
+
+ expect(mockFetch).toHaveBeenCalledTimes(3);
+ });
+
+ it('starts a new preparation after the previous request succeeds', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await emailAddress.prepareVerification(params);
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('starts a new preparation after the previous request fails', async () => {
+ const mockFetch = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('prepare failed'))
+ .mockResolvedValueOnce({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await expect(emailAddress.prepareVerification(params)).rejects.toThrow('prepare failed');
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not coalesce preparations across EmailAddress instances', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const firstEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const secondEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = firstEmailAddress.prepareVerification(params);
+ const second = secondEmailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce concurrent verification attempts', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { code: '123456' };
+
+ const first = emailAddress.attemptVerification(params);
+ const second = emailAddress.attemptVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+ });
+});

.changeset/calm-codes-share.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-js": patch
+---
+
+Prevent overlapping verification preparations from triggering duplicate verification sends during sign-in, sign-up, and when verifying an email address, phone number, or web3 wallet from the user profile.

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

@@ -25,8 +25,18 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
 export type BaseMutateParams = {
  action?: string;
  body?: any;
+ coalesce?: boolean;
  method?: HTTPMethod;
  path?: string;
+ signal?: AbortSignal;
+};
+
+const COALESCED_POST_TTL_MS = 30_000;
+
+type PendingCoalescedPost<T> = {
+ promise: Promise<T>;
+ controller: AbortController;
+ expiresAt: number;
 };
 
 function assertProductionKeysOnDev(statusCode: number, payloadErrors?: ClerkAPIErrorJSON[]) {
@@ -58,6 +68,8 @@ export abstract class BaseResource {
  id?: string;
  pathRoot = '';
 
+ #pendingCoalescedPosts?: Map<string, PendingCoalescedPost<this>>;
+
  static get fapiClient(): FapiClient {
  return BaseResource.clerk.getFapiClient();
  }
@@ -217,9 +229,9 @@ export abstract class BaseResource {
  }
 
  protected async _baseMutate<J extends ClerkResourceJSON | null>(params: BaseMutateParams): Promise<this> {
- const { action, body, method, path } = params;
+ const { action, body, method, path, signal } = params;
  // TODO @userland-errors:
- const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body });
+ const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body, signal });
  return this.fromJSON((json?.response || json) as J);
  }
 
@@ -230,7 +242,32 @@ export abstract class BaseResource {
  }
 
  protected async _basePost<J extends ClerkResourceJSON | null>(params: BaseMutateParams = {}): Promise<this> {
- return this._baseMutate<J>({ ...params, method: 'POST' });
+ if (!params.coalesce) {
+ return this._baseMutate<J>({ ...params, method: 'POST' });
+ }
+
+ const key = this.#coalescedPostKey(params);
+ const posts = (this.#pendingCoalescedPosts ??= new Map());
+ const pending = posts.get(key);
+ if (pending && Date.now() < pending.expiresAt) {
+ return pending.promise;
+ }
+
+ const controller = new AbortController();
+ const promise = this._baseMutate<J>({ ...params, method: 'POST', signal: controller.signal }).finally(() => {
+ if (posts.get(key)?.promise === promise) {
+ posts.delete(key);
+ }
+ });
+ posts.set(key, { promise, controller, expiresAt: Date.now() + COALESCED_POST_TTL_MS });
+ return promise;
+ }
+
+ #coalescedPostKey(params: BaseMutateParams): string {
+ const body = Object.entries(params.body ?? {})
+ .filter(([, value]) => value !== undefined)
+ .sort(([left], [right]) => (left < right ? -1 : 1));
+ return JSON.stringify([this.id, params.path, params.action, body]);
  }
 
  protected async _basePostBypass<J extends ClerkResourceJSON>(params: BaseMutateParams = {}): Promise<this> {

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

@@ -38,6 +38,7 @@ export class EmailAddress extends BaseResource implements EmailAddressResource {
  prepareVerification = (params: PrepareEmailAddressVerificationParams): Promise<this> => {
  return this._basePost<EmailAddressJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

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

@@ -34,6 +34,7 @@ export class PhoneNumber extends BaseResource implements PhoneNumberResource {
  prepareVerification = (): Promise<PhoneNumberResource> => {
  return this._basePost<PhoneNumberJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { strategy: 'phone_code' },
  });
  };

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

@@ -265,6 +265,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: { ...config, strategy: params.strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  };
 
@@ -356,6 +357,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: params,
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  };
 
@@ -883,6 +885,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'reset_password_email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -926,6 +929,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'reset_password_phone_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1083,6 +1087,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1135,6 +1140,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'email_link',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1187,6 +1193,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1252,6 +1259,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'enterprise_sso',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1319,6 +1327,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { web3WalletId: web3FirstFactor.web3WalletId, strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
 
  const { message } = this.firstFactorVerification;
@@ -1390,6 +1399,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'passkey' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1442,6 +1452,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'phone_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }
@@ -1468,6 +1479,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'email_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }

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

@@ -188,6 +188,7 @@ export class SignUp extends BaseResource implements SignUpResource {
  return this._basePost({
  body: params,
  action: 'prepare_verification',
+ coalesce: true,
  });
  };
 
@@ -973,6 +974,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_code' },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -993,6 +995,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'phone_code', channel },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1020,6 +1023,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_link', redirectUrl: absoluteVerificationUrl },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1163,6 +1167,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy },
  action: 'prepare_verification',
+ coalesce: true,
  });
 
  const { message } = this.#resource.verifications.web3Wallet;

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

@@ -30,6 +30,7 @@ export class Web3Wallet extends BaseResource implements Web3WalletResource {
  prepareVerification = (params: PrepareWeb3WalletVerificationParams): Promise<this> => {
  return this._basePost<Web3WalletJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

packages/clerk-js/src/core/resources/__tests__/EmailAddress.test.ts

@@ -0,0 +1,123 @@
+import type { EmailAddressJSON } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, EmailAddress } from '../internal';
+
+describe('EmailAddress', () => {
+ describe('prepareVerification', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('coalesces concurrent identical preparations', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = emailAddress.prepareVerification(params);
+ const second = emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce preparations with different strategies or params', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+
+ await Promise.all([
+ emailAddress.prepareVerification({ strategy: 'email_code' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-one' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-two' }),
+ ]);
+
+ expect(mockFetch).toHaveBeenCalledTimes(3);
+ });
+
+ it('starts a new preparation after the previous request succeeds', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await emailAddress.prepareVerification(params);
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('starts a new preparation after the previous request fails', async () => {
+ const mockFetch = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('prepare failed'))
+ .mockResolvedValueOnce({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await expect(emailAddress.prepareVerification(params)).rejects.toThrow('prepare failed');
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not coalesce preparations across EmailAddress instances', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const firstEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const secondEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = firstEmailAddress.prepareVerification(params);
+ const second = secondEmailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce concurrent verification attempts', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { code: '123456' };
+
+ const first = emailAddress.attemptVerification(params);
+ const second = emailAddress.attemptVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+ });
+});

.changeset/calm-codes-share.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-js": patch
+---
+
+Prevent overlapping verification preparations from triggering duplicate verification sends during sign-in, sign-up, and when verifying an email address, phone number, or web3 wallet from the user profile.

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

@@ -25,8 +25,18 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
 export type BaseMutateParams = {
  action?: string;
  body?: any;
+ coalesce?: boolean;
  method?: HTTPMethod;
  path?: string;
+ signal?: AbortSignal;
+};
+
+const COALESCED_POST_TTL_MS = 30_000;
+
+type PendingCoalescedPost<T> = {
+ promise: Promise<T>;
+ controller: AbortController;
+ expiresAt: number;
 };
 
 function assertProductionKeysOnDev(statusCode: number, payloadErrors?: ClerkAPIErrorJSON[]) {
@@ -58,6 +68,8 @@ export abstract class BaseResource {
  id?: string;
  pathRoot = '';
 
+ #pendingCoalescedPosts?: Map<string, PendingCoalescedPost<this>>;
+
  static get fapiClient(): FapiClient {
  return BaseResource.clerk.getFapiClient();
  }
@@ -217,9 +229,9 @@ export abstract class BaseResource {
  }
 
  protected async _baseMutate<J extends ClerkResourceJSON | null>(params: BaseMutateParams): Promise<this> {
- const { action, body, method, path } = params;
+ const { action, body, method, path, signal } = params;
  // TODO @userland-errors:
- const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body });
+ const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body, signal });
  return this.fromJSON((json?.response || json) as J);
  }
 
@@ -230,7 +242,32 @@ export abstract class BaseResource {
  }
 
  protected async _basePost<J extends ClerkResourceJSON | null>(params: BaseMutateParams = {}): Promise<this> {
- return this._baseMutate<J>({ ...params, method: 'POST' });
+ if (!params.coalesce) {
+ return this._baseMutate<J>({ ...params, method: 'POST' });
+ }
+
+ const key = this.#coalescedPostKey(params);
+ const posts = (this.#pendingCoalescedPosts ??= new Map());
+ const pending = posts.get(key);
+ if (pending && Date.now() < pending.expiresAt) {
+ return pending.promise;
+ }
+
+ const controller = new AbortController();
+ const promise = this._baseMutate<J>({ ...params, method: 'POST', signal: controller.signal }).finally(() => {
+ if (posts.get(key)?.promise === promise) {
+ posts.delete(key);
+ }
+ });
+ posts.set(key, { promise, controller, expiresAt: Date.now() + COALESCED_POST_TTL_MS });
+ return promise;
+ }
+
+ #coalescedPostKey(params: BaseMutateParams): string {
+ const body = Object.entries(params.body ?? {})
+ .filter(([, value]) => value !== undefined)
+ .sort(([left], [right]) => (left < right ? -1 : 1));
+ return JSON.stringify([this.id, params.path, params.action, body]);
  }
 
  protected async _basePostBypass<J extends ClerkResourceJSON>(params: BaseMutateParams = {}): Promise<this> {

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

@@ -38,6 +38,7 @@ export class EmailAddress extends BaseResource implements EmailAddressResource {
  prepareVerification = (params: PrepareEmailAddressVerificationParams): Promise<this> => {
  return this._basePost<EmailAddressJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

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

@@ -34,6 +34,7 @@ export class PhoneNumber extends BaseResource implements PhoneNumberResource {
  prepareVerification = (): Promise<PhoneNumberResource> => {
  return this._basePost<PhoneNumberJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { strategy: 'phone_code' },
  });
  };

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

@@ -265,6 +265,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: { ...config, strategy: params.strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  };
 
@@ -356,6 +357,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: params,
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  };
 
@@ -883,6 +885,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'reset_password_email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -926,6 +929,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'reset_password_phone_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1083,6 +1087,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1135,6 +1140,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'email_link',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1187,6 +1193,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1252,6 +1259,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'enterprise_sso',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1319,6 +1327,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { web3WalletId: web3FirstFactor.web3WalletId, strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
 
  const { message } = this.firstFactorVerification;
@@ -1390,6 +1399,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'passkey' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1442,6 +1452,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'phone_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }
@@ -1468,6 +1479,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'email_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }

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

@@ -188,6 +188,7 @@ export class SignUp extends BaseResource implements SignUpResource {
  return this._basePost({
  body: params,
  action: 'prepare_verification',
+ coalesce: true,
  });
  };
 
@@ -973,6 +974,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_code' },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -993,6 +995,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'phone_code', channel },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1020,6 +1023,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_link', redirectUrl: absoluteVerificationUrl },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1163,6 +1167,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy },
  action: 'prepare_verification',
+ coalesce: true,
  });
 
  const { message } = this.#resource.verifications.web3Wallet;

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

@@ -30,6 +30,7 @@ export class Web3Wallet extends BaseResource implements Web3WalletResource {
  prepareVerification = (params: PrepareWeb3WalletVerificationParams): Promise<this> => {
  return this._basePost<Web3WalletJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

packages/clerk-js/src/core/resources/__tests__/EmailAddress.test.ts

@@ -0,0 +1,123 @@
+import type { EmailAddressJSON } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, EmailAddress } from '../internal';
+
+describe('EmailAddress', () => {
+ describe('prepareVerification', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('coalesces concurrent identical preparations', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = emailAddress.prepareVerification(params);
+ const second = emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce preparations with different strategies or params', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+
+ await Promise.all([
+ emailAddress.prepareVerification({ strategy: 'email_code' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-one' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-two' }),
+ ]);
+
+ expect(mockFetch).toHaveBeenCalledTimes(3);
+ });
+
+ it('starts a new preparation after the previous request succeeds', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await emailAddress.prepareVerification(params);
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('starts a new preparation after the previous request fails', async () => {
+ const mockFetch = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('prepare failed'))
+ .mockResolvedValueOnce({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await expect(emailAddress.prepareVerification(params)).rejects.toThrow('prepare failed');
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not coalesce preparations across EmailAddress instances', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const firstEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const secondEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = firstEmailAddress.prepareVerification(params);
+ const second = secondEmailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce concurrent verification attempts', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { code: '123456' };
+
+ const first = emailAddress.attemptVerification(params);
+ const second = emailAddress.attemptVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+ });
+});

.changeset/calm-codes-share.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-js": patch
+---
+
+Prevent overlapping verification preparations from triggering duplicate verification sends during sign-in, sign-up, and when verifying an email address, phone number, or web3 wallet from the user profile.

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

@@ -25,8 +25,18 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
 export type BaseMutateParams = {
  action?: string;
  body?: any;
+ coalesce?: boolean;
  method?: HTTPMethod;
  path?: string;
+ signal?: AbortSignal;
+};
+
+const COALESCED_POST_TTL_MS = 30_000;
+
+type PendingCoalescedPost<T> = {
+ promise: Promise<T>;
+ controller: AbortController;
+ expiresAt: number;
 };
 
 function assertProductionKeysOnDev(statusCode: number, payloadErrors?: ClerkAPIErrorJSON[]) {
@@ -58,6 +68,8 @@ export abstract class BaseResource {
  id?: string;
  pathRoot = '';
 
+ #pendingCoalescedPosts?: Map<string, PendingCoalescedPost<this>>;
+
  static get fapiClient(): FapiClient {
  return BaseResource.clerk.getFapiClient();
  }
@@ -217,9 +229,9 @@ export abstract class BaseResource {
  }
 
  protected async _baseMutate<J extends ClerkResourceJSON | null>(params: BaseMutateParams): Promise<this> {
- const { action, body, method, path } = params;
+ const { action, body, method, path, signal } = params;
  // TODO @userland-errors:
- const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body });
+ const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body, signal });
  return this.fromJSON((json?.response || json) as J);
  }
 
@@ -230,7 +242,32 @@ export abstract class BaseResource {
  }
 
  protected async _basePost<J extends ClerkResourceJSON | null>(params: BaseMutateParams = {}): Promise<this> {
- return this._baseMutate<J>({ ...params, method: 'POST' });
+ if (!params.coalesce) {
+ return this._baseMutate<J>({ ...params, method: 'POST' });
+ }
+
+ const key = this.#coalescedPostKey(params);
+ const posts = (this.#pendingCoalescedPosts ??= new Map());
+ const pending = posts.get(key);
+ if (pending && Date.now() < pending.expiresAt) {
+ return pending.promise;
+ }
+
+ const controller = new AbortController();
+ const promise = this._baseMutate<J>({ ...params, method: 'POST', signal: controller.signal }).finally(() => {
+ if (posts.get(key)?.promise === promise) {
+ posts.delete(key);
+ }
+ });
+ posts.set(key, { promise, controller, expiresAt: Date.now() + COALESCED_POST_TTL_MS });
+ return promise;
+ }
+
+ #coalescedPostKey(params: BaseMutateParams): string {
+ const body = Object.entries(params.body ?? {})
+ .filter(([, value]) => value !== undefined)
+ .sort(([left], [right]) => (left < right ? -1 : 1));
+ return JSON.stringify([this.id, params.path, params.action, body]);
  }
 
  protected async _basePostBypass<J extends ClerkResourceJSON>(params: BaseMutateParams = {}): Promise<this> {

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

@@ -38,6 +38,7 @@ export class EmailAddress extends BaseResource implements EmailAddressResource {
  prepareVerification = (params: PrepareEmailAddressVerificationParams): Promise<this> => {
  return this._basePost<EmailAddressJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

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

@@ -34,6 +34,7 @@ export class PhoneNumber extends BaseResource implements PhoneNumberResource {
  prepareVerification = (): Promise<PhoneNumberResource> => {
  return this._basePost<PhoneNumberJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { strategy: 'phone_code' },
  });
  };

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

@@ -265,6 +265,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: { ...config, strategy: params.strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  };
 
@@ -356,6 +357,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: params,
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  };
 
@@ -883,6 +885,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'reset_password_email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -926,6 +929,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'reset_password_phone_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1083,6 +1087,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1135,6 +1140,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'email_link',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1187,6 +1193,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1252,6 +1259,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'enterprise_sso',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1319,6 +1327,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { web3WalletId: web3FirstFactor.web3WalletId, strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
 
  const { message } = this.firstFactorVerification;
@@ -1390,6 +1399,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'passkey' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1442,6 +1452,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'phone_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }
@@ -1468,6 +1479,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'email_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }

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

@@ -188,6 +188,7 @@ export class SignUp extends BaseResource implements SignUpResource {
  return this._basePost({
  body: params,
  action: 'prepare_verification',
+ coalesce: true,
  });
  };
 
@@ -973,6 +974,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_code' },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -993,6 +995,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'phone_code', channel },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1020,6 +1023,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_link', redirectUrl: absoluteVerificationUrl },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1163,6 +1167,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy },
  action: 'prepare_verification',
+ coalesce: true,
  });
 
  const { message } = this.#resource.verifications.web3Wallet;

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

@@ -30,6 +30,7 @@ export class Web3Wallet extends BaseResource implements Web3WalletResource {
  prepareVerification = (params: PrepareWeb3WalletVerificationParams): Promise<this> => {
  return this._basePost<Web3WalletJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

packages/clerk-js/src/core/resources/__tests__/EmailAddress.test.ts

@@ -0,0 +1,123 @@
+import type { EmailAddressJSON } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, EmailAddress } from '../internal';
+
+describe('EmailAddress', () => {
+ describe('prepareVerification', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('coalesces concurrent identical preparations', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = emailAddress.prepareVerification(params);
+ const second = emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce preparations with different strategies or params', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+
+ await Promise.all([
+ emailAddress.prepareVerification({ strategy: 'email_code' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-one' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-two' }),
+ ]);
+
+ expect(mockFetch).toHaveBeenCalledTimes(3);
+ });
+
+ it('starts a new preparation after the previous request succeeds', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await emailAddress.prepareVerification(params);
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('starts a new preparation after the previous request fails', async () => {
+ const mockFetch = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('prepare failed'))
+ .mockResolvedValueOnce({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await expect(emailAddress.prepareVerification(params)).rejects.toThrow('prepare failed');
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not coalesce preparations across EmailAddress instances', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const firstEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const secondEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = firstEmailAddress.prepareVerification(params);
+ const second = secondEmailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce concurrent verification attempts', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { code: '123456' };
+
+ const first = emailAddress.attemptVerification(params);
+ const second = emailAddress.attemptVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+ });
+});

.changeset/calm-codes-share.md

@@ -0,0 +1,5 @@
+---
+"@clerk/clerk-js": patch
+---
+
+Prevent overlapping verification preparations from triggering duplicate verification sends during sign-in, sign-up, and when verifying an email address, phone number, or web3 wallet from the user profile.

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

@@ -25,8 +25,18 @@ export type BaseFetchOptions = ClerkResourceReloadParams & {
 export type BaseMutateParams = {
  action?: string;
  body?: any;
+ coalesce?: boolean;
  method?: HTTPMethod;
  path?: string;
+ signal?: AbortSignal;
+};
+
+const COALESCED_POST_TTL_MS = 30_000;
+
+type PendingCoalescedPost<T> = {
+ promise: Promise<T>;
+ controller: AbortController;
+ expiresAt: number;
 };
 
 function assertProductionKeysOnDev(statusCode: number, payloadErrors?: ClerkAPIErrorJSON[]) {
@@ -58,6 +68,8 @@ export abstract class BaseResource {
  id?: string;
  pathRoot = '';
 
+ #pendingCoalescedPosts?: Map<string, PendingCoalescedPost<this>>;
+
  static get fapiClient(): FapiClient {
  return BaseResource.clerk.getFapiClient();
  }
@@ -217,9 +229,9 @@ export abstract class BaseResource {
  }
 
  protected async _baseMutate<J extends ClerkResourceJSON | null>(params: BaseMutateParams): Promise<this> {
- const { action, body, method, path } = params;
+ const { action, body, method, path, signal } = params;
  // TODO @userland-errors:
- const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body });
+ const json = await BaseResource._fetch<J>({ method, path: path || this.path(action), body, signal });
  return this.fromJSON((json?.response || json) as J);
  }
 
@@ -230,7 +242,32 @@ export abstract class BaseResource {
  }
 
  protected async _basePost<J extends ClerkResourceJSON | null>(params: BaseMutateParams = {}): Promise<this> {
- return this._baseMutate<J>({ ...params, method: 'POST' });
+ if (!params.coalesce) {
+ return this._baseMutate<J>({ ...params, method: 'POST' });
+ }
+
+ const key = this.#coalescedPostKey(params);
+ const posts = (this.#pendingCoalescedPosts ??= new Map());
+ const pending = posts.get(key);
+ if (pending && Date.now() < pending.expiresAt) {
+ return pending.promise;
+ }
+
+ const controller = new AbortController();
+ const promise = this._baseMutate<J>({ ...params, method: 'POST', signal: controller.signal }).finally(() => {
+ if (posts.get(key)?.promise === promise) {
+ posts.delete(key);
+ }
+ });
+ posts.set(key, { promise, controller, expiresAt: Date.now() + COALESCED_POST_TTL_MS });
+ return promise;
+ }
+
+ #coalescedPostKey(params: BaseMutateParams): string {
+ const body = Object.entries(params.body ?? {})
+ .filter(([, value]) => value !== undefined)
+ .sort(([left], [right]) => (left < right ? -1 : 1));
+ return JSON.stringify([this.id, params.path, params.action, body]);
  }
 
  protected async _basePostBypass<J extends ClerkResourceJSON>(params: BaseMutateParams = {}): Promise<this> {

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

@@ -38,6 +38,7 @@ export class EmailAddress extends BaseResource implements EmailAddressResource {
  prepareVerification = (params: PrepareEmailAddressVerificationParams): Promise<this> => {
  return this._basePost<EmailAddressJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

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

@@ -34,6 +34,7 @@ export class PhoneNumber extends BaseResource implements PhoneNumberResource {
  prepareVerification = (): Promise<PhoneNumberResource> => {
  return this._basePost<PhoneNumberJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { strategy: 'phone_code' },
  });
  };

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

@@ -265,6 +265,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: { ...config, strategy: params.strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  };
 
@@ -356,6 +357,7 @@ export class SignIn extends BaseResource implements SignInResource {
  return this._basePost({
  body: params,
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  };
 
@@ -883,6 +885,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'reset_password_email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -926,6 +929,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'reset_password_phone_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1083,6 +1087,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId: emailCodeFactor.emailAddressId, strategy: 'email_code' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1135,6 +1140,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'email_link',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1187,6 +1193,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId: phoneCodeFactor.phoneNumberId, strategy: 'phone_code', channel },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  });
  }
@@ -1252,6 +1259,7 @@ class SignInFuture implements SignInFutureResource {
  strategy: 'enterprise_sso',
  },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1319,6 +1327,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { web3WalletId: web3FirstFactor.web3WalletId, strategy },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
 
  const { message } = this.firstFactorVerification;
@@ -1390,6 +1399,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'passkey' },
  action: 'prepare_first_factor',
+ coalesce: true,
  });
  }
 
@@ -1442,6 +1452,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { phoneNumberId, strategy: 'phone_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }
@@ -1468,6 +1479,7 @@ class SignInFuture implements SignInFutureResource {
  await this.#resource.__internal_basePost({
  body: { emailAddressId, strategy: 'email_code' },
  action: 'prepare_second_factor',
+ coalesce: true,
  });
  });
  }

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

@@ -188,6 +188,7 @@ export class SignUp extends BaseResource implements SignUpResource {
  return this._basePost({
  body: params,
  action: 'prepare_verification',
+ coalesce: true,
  });
  };
 
@@ -973,6 +974,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_code' },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -993,6 +995,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'phone_code', channel },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1020,6 +1023,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy: 'email_link', redirectUrl: absoluteVerificationUrl },
  action: 'prepare_verification',
+ coalesce: true,
  });
  });
  }
@@ -1163,6 +1167,7 @@ class SignUpFuture implements SignUpFutureResource {
  await this.#resource.__internal_basePost({
  body: { strategy },
  action: 'prepare_verification',
+ coalesce: true,
  });
 
  const { message } = this.#resource.verifications.web3Wallet;

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

@@ -30,6 +30,7 @@ export class Web3Wallet extends BaseResource implements Web3WalletResource {
  prepareVerification = (params: PrepareWeb3WalletVerificationParams): Promise<this> => {
  return this._basePost<Web3WalletJSON>({
  action: 'prepare_verification',
+ coalesce: true,
  body: { ...params },
  });
  };

packages/clerk-js/src/core/resources/__tests__/EmailAddress.test.ts

@@ -0,0 +1,123 @@
+import type { EmailAddressJSON } from '@clerk/shared/types';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { BaseResource, EmailAddress } from '../internal';
+
+describe('EmailAddress', () => {
+ describe('prepareVerification', () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it('coalesces concurrent identical preparations', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = emailAddress.prepareVerification(params);
+ const second = emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(1);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce preparations with different strategies or params', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+
+ await Promise.all([
+ emailAddress.prepareVerification({ strategy: 'email_code' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-one' }),
+ emailAddress.prepareVerification({ strategy: 'email_link', redirectUrl: '/verify-two' }),
+ ]);
+
+ expect(mockFetch).toHaveBeenCalledTimes(3);
+ });
+
+ it('starts a new preparation after the previous request succeeds', async () => {
+ const mockFetch = vi.fn().mockResolvedValue({
+ response: { id: 'email_123' },
+ });
+ // @ts-ignore
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await emailAddress.prepareVerification(params);
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('starts a new preparation after the previous request fails', async () => {
+ const mockFetch = vi
+ .fn()
+ .mockRejectedValueOnce(new Error('prepare failed'))
+ .mockResolvedValueOnce({
+ response: { id: 'email_123' },
+ });
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ await expect(emailAddress.prepareVerification(params)).rejects.toThrow('prepare failed');
+ await emailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not coalesce preparations across EmailAddress instances', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const firstEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const secondEmailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { strategy: 'email_code' as const };
+
+ const first = firstEmailAddress.prepareVerification(params);
+ const second = secondEmailAddress.prepareVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+
+ it('does not coalesce concurrent verification attempts', async () => {
+ const deferred = createDeferredPromise<any>();
+ const mockFetch = vi.fn().mockReturnValue(deferred.promise);
+ BaseResource._fetch = mockFetch;
+
+ const emailAddress = new EmailAddress({ id: 'email_123' } as EmailAddressJSON, '/me/email_addresses');
+ const params = { code: '123456' };
+
+ const first = emailAddress.attemptVerification(params);
+ const second = emailAddress.attemptVerification(params);
+
+ expect(mockFetch).toHaveBeenCalledTimes(2);
+
+ deferred.resolve({
+ response: { id: 'email_123' },
+ });
+ await Promise.all([first, second]);
+ });
+ });
+});