feat(clerk-js,shared): Add onBeforeRetry to FAPI client

.changeset/poor-memes-wish.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add retry attempt tracking to FAPI client GET requests
+
+The FAPI client now adds a `_clerk_retry_attempt` query parameter to retry attempts for GET requests, allowing servers to track and handle retry scenarios appropriately. This parameter is only added during retry attempts, not on the initial request.

packages/clerk-js/src/core/__tests__/fapiClient.spec.ts

@@ -1,5 +1,5 @@
 import type { InstanceType } from '@clerk/types';
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { SUPPORTED_FAPI_VERSION } from '../constants';
 import { createFapiClient } from '../fapiClient';
@@ -64,7 +64,7 @@ beforeAll(() => {
 });
 
 beforeEach(() => {
- (global.fetch as vi.Mock).mockClear();
+ (global.fetch as Mock).mockClear();
 });
 
 afterAll(() => {
@@ -183,33 +183,33 @@ describe('request', () => {
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `https://clerk.example.com/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('invokes global.fetch with proxy', async () => {
  await fapiClientWithProxy.request({
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `${proxyUrl}/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('returns array response as array', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  headers: {
  get: vi.fn(() => 'sess_43'),
@@ -226,7 +226,7 @@ describe('request', () => {
  });
 
  it('handles the empty body on 204 response, returning null', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  status: 204,
  json: () => {
@@ -251,4 +251,65 @@ describe('request', () => {
  it.todo('appends the __clerk_db_jwt cookie value to the query string');
  it.todo('sets the __clerk_db_jwt cookie from the response Clerk-Cookie header');
  });
+
+ describe('retry logic', () => {
+ it('does not send retry query parameter on initial request', async () => {
+ await fapiClient.request({
+ path: '/foo',
+ });
+
+ expect(fetch).toHaveBeenCalledWith(expect.not.stringMatching(/_clerk_retry_attempt=/), expect.any(Object));
+ });
+
+ it('sends retry query parameter on retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount === 1) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=1/);
+ });
+
+ it('increments retry query parameter on multiple retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount <= 2) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+
+ const thirdCall = (fetch as Mock).mock.calls[2];
+ expect(thirdCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+ });
+ });
 });

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

@@ -227,7 +227,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // avoid triggering a CORS OPTION request as it currently breaks cookie dropping in Safari.
  const overwrittenRequestMethod = method === 'GET' ? 'GET' : 'POST';
  let response: Response;
- const urlStr = requestInit.url.toString();
+ const url = requestInit.url;
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
  method: overwrittenRequestMethod,
@@ -237,7 +237,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response = await retry(() => fetch(urlStr, fetchOpts), {
+ response = await retry(() => fetch(url, fetchOpts), {
  // This retry handles only network errors, not 4xx or 5xx responses,
  // so we want to try once immediately to handle simple network blips.
  // Since fapiClient is responsible for the network layer only,
@@ -250,11 +250,17 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // We want to retry only GET requests, as other methods are not idempotent.
  return overwrittenRequestMethod === 'GET' && iterations < maxTries;
  },
+ onBeforeRetry: (iteration: number): void => {
+ // Add the retry attempt to the query string params.
+ // We use params to keep the request simple for CORS.
+ url.searchParams.set('_clerk_retry_attempt', iteration.toString());
+ },
  });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }
  } catch (e) {
+ const urlStr = url.toString();
  debugLogger.error('network error', { error: e, url: urlStr, method }, 'fapiClient');
  clerkNetworkError(urlStr, e);
  }

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

@@ -30,16 +30,15 @@ describe('Token', () => {
  message: '500',
  });
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
 
  describe('with offline browser and network failure', () => {
@@ -67,16 +66,15 @@ describe('Token', () => {
 
  const token = await Token.create('/path/to/tokens');
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
 
  expect(token.getRawString()).toEqual('');
  expect(warnSpy).toBeCalled();
@@ -92,16 +90,15 @@ describe('Token', () => {
  `ClerkJS: Network error at "https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test" - TypeError: Failed to fetch. Please try again.`,
  );
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
  });
  });

packages/shared/src/retry.ts

@@ -3,18 +3,21 @@ type Milliseconds = number;
 type RetryOptions = Partial<{
  /**
  * The initial delay before the first retry.
+ *
  * @default 125
  */
  initialDelay: Milliseconds;
  /**
  * The maximum delay between retries.
  * The delay between retries will never exceed this value.
  * If set to 0, the delay will increase indefinitely.
+ *
  * @default 0
  */
  maxDelayBetweenRetries: Milliseconds;
  /**
  * The multiplier for the exponential backoff.
+ *
  * @default 2
  */
  factor: number;
@@ -23,23 +26,33 @@ type RetryOptions = Partial<{
  * The callback accepts the error that was thrown and the number of iterations.
  * The iterations variable references the number of retries AFTER attempt
  * that caused the error and starts at 1 (as in, this is the 1st, 2nd, nth retry).
+ *
  * @default (error, iterations) => iterations < 5
  */
  shouldRetry: (error: unknown, iterations: number) => boolean;
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
+ *
  * @default false
  */
  retryImmediately: boolean;
  /**
  * If true, the intervals will be multiplied by a factor in the range of [1,2].
+ *
  * @default true
  */
  jitter: boolean;
+
+ /**
+ * A callback that is invoked before each retry attempt.
+ * The callback receives the iteration number (starting from 1 for the first retry).
+ * This can be used to modify request parameters, add headers, etc.
+ */
+ onBeforeRetry?: (iteration: number) => void | Promise<void>;
 }>;
 
-const defaultOptions: Required<RetryOptions> = {
+const defaultOptions = {
  initialDelay: 125,
  maxDelayBetweenRetries: 0,
  factor: 2,
@@ -81,7 +94,7 @@ const createExponentialDelayAsyncFn = (
  */
 export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOptions = {}): Promise<T> => {
  let iterations = 0;
- const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter } = {
+ const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter, onBeforeRetry } = {
  ...defaultOptions,
  ...options,
  };
@@ -101,6 +114,11 @@ export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOpt
  if (!shouldRetry(e, iterations)) {
  throw e;
  }
+
+ if (onBeforeRetry) {
+ await onBeforeRetry(iterations);
+ }
+
  if (retryImmediately && iterations === 1) {
  await sleep(applyJitter(RETRY_IMMEDIATELY_DELAY, jitter));
  } else {

.changeset/poor-memes-wish.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add retry attempt tracking to FAPI client GET requests
+
+The FAPI client now adds a `_clerk_retry_attempt` query parameter to retry attempts for GET requests, allowing servers to track and handle retry scenarios appropriately. This parameter is only added during retry attempts, not on the initial request.

packages/clerk-js/src/core/__tests__/fapiClient.spec.ts

@@ -1,5 +1,5 @@
 import type { InstanceType } from '@clerk/types';
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { SUPPORTED_FAPI_VERSION } from '../constants';
 import { createFapiClient } from '../fapiClient';
@@ -64,7 +64,7 @@ beforeAll(() => {
 });
 
 beforeEach(() => {
- (global.fetch as vi.Mock).mockClear();
+ (global.fetch as Mock).mockClear();
 });
 
 afterAll(() => {
@@ -183,33 +183,33 @@ describe('request', () => {
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `https://clerk.example.com/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('invokes global.fetch with proxy', async () => {
  await fapiClientWithProxy.request({
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `${proxyUrl}/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('returns array response as array', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  headers: {
  get: vi.fn(() => 'sess_43'),
@@ -226,7 +226,7 @@ describe('request', () => {
  });
 
  it('handles the empty body on 204 response, returning null', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  status: 204,
  json: () => {
@@ -251,4 +251,65 @@ describe('request', () => {
  it.todo('appends the __clerk_db_jwt cookie value to the query string');
  it.todo('sets the __clerk_db_jwt cookie from the response Clerk-Cookie header');
  });
+
+ describe('retry logic', () => {
+ it('does not send retry query parameter on initial request', async () => {
+ await fapiClient.request({
+ path: '/foo',
+ });
+
+ expect(fetch).toHaveBeenCalledWith(expect.not.stringMatching(/_clerk_retry_attempt=/), expect.any(Object));
+ });
+
+ it('sends retry query parameter on retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount === 1) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=1/);
+ });
+
+ it('increments retry query parameter on multiple retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount <= 2) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+
+ const thirdCall = (fetch as Mock).mock.calls[2];
+ expect(thirdCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+ });
+ });
 });

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

@@ -227,7 +227,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // avoid triggering a CORS OPTION request as it currently breaks cookie dropping in Safari.
  const overwrittenRequestMethod = method === 'GET' ? 'GET' : 'POST';
  let response: Response;
- const urlStr = requestInit.url.toString();
+ const url = requestInit.url;
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
  method: overwrittenRequestMethod,
@@ -237,7 +237,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response = await retry(() => fetch(urlStr, fetchOpts), {
+ response = await retry(() => fetch(url, fetchOpts), {
  // This retry handles only network errors, not 4xx or 5xx responses,
  // so we want to try once immediately to handle simple network blips.
  // Since fapiClient is responsible for the network layer only,
@@ -250,11 +250,17 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // We want to retry only GET requests, as other methods are not idempotent.
  return overwrittenRequestMethod === 'GET' && iterations < maxTries;
  },
+ onBeforeRetry: (iteration: number): void => {
+ // Add the retry attempt to the query string params.
+ // We use params to keep the request simple for CORS.
+ url.searchParams.set('_clerk_retry_attempt', iteration.toString());
+ },
  });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }
  } catch (e) {
+ const urlStr = url.toString();
  debugLogger.error('network error', { error: e, url: urlStr, method }, 'fapiClient');
  clerkNetworkError(urlStr, e);
  }

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

@@ -30,16 +30,15 @@ describe('Token', () => {
  message: '500',
  });
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
 
  describe('with offline browser and network failure', () => {
@@ -67,16 +66,15 @@ describe('Token', () => {
 
  const token = await Token.create('/path/to/tokens');
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
 
  expect(token.getRawString()).toEqual('');
  expect(warnSpy).toBeCalled();
@@ -92,16 +90,15 @@ describe('Token', () => {
  `ClerkJS: Network error at "https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test" - TypeError: Failed to fetch. Please try again.`,
  );
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
  });
  });

packages/shared/src/retry.ts

@@ -3,18 +3,21 @@ type Milliseconds = number;
 type RetryOptions = Partial<{
  /**
  * The initial delay before the first retry.
+ *
  * @default 125
  */
  initialDelay: Milliseconds;
  /**
  * The maximum delay between retries.
  * The delay between retries will never exceed this value.
  * If set to 0, the delay will increase indefinitely.
+ *
  * @default 0
  */
  maxDelayBetweenRetries: Milliseconds;
  /**
  * The multiplier for the exponential backoff.
+ *
  * @default 2
  */
  factor: number;
@@ -23,23 +26,33 @@ type RetryOptions = Partial<{
  * The callback accepts the error that was thrown and the number of iterations.
  * The iterations variable references the number of retries AFTER attempt
  * that caused the error and starts at 1 (as in, this is the 1st, 2nd, nth retry).
+ *
  * @default (error, iterations) => iterations < 5
  */
  shouldRetry: (error: unknown, iterations: number) => boolean;
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
+ *
  * @default false
  */
  retryImmediately: boolean;
  /**
  * If true, the intervals will be multiplied by a factor in the range of [1,2].
+ *
  * @default true
  */
  jitter: boolean;
+
+ /**
+ * A callback that is invoked before each retry attempt.
+ * The callback receives the iteration number (starting from 1 for the first retry).
+ * This can be used to modify request parameters, add headers, etc.
+ */
+ onBeforeRetry?: (iteration: number) => void | Promise<void>;
 }>;
 
-const defaultOptions: Required<RetryOptions> = {
+const defaultOptions = {
  initialDelay: 125,
  maxDelayBetweenRetries: 0,
  factor: 2,
@@ -81,7 +94,7 @@ const createExponentialDelayAsyncFn = (
  */
 export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOptions = {}): Promise<T> => {
  let iterations = 0;
- const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter } = {
+ const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter, onBeforeRetry } = {
  ...defaultOptions,
  ...options,
  };
@@ -101,6 +114,11 @@ export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOpt
  if (!shouldRetry(e, iterations)) {
  throw e;
  }
+
+ if (onBeforeRetry) {
+ await onBeforeRetry(iterations);
+ }
+
  if (retryImmediately && iterations === 1) {
  await sleep(applyJitter(RETRY_IMMEDIATELY_DELAY, jitter));
  } else {

.changeset/poor-memes-wish.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add retry attempt tracking to FAPI client GET requests
+
+The FAPI client now adds a `_clerk_retry_attempt` query parameter to retry attempts for GET requests, allowing servers to track and handle retry scenarios appropriately. This parameter is only added during retry attempts, not on the initial request.

packages/clerk-js/src/core/__tests__/fapiClient.spec.ts

@@ -1,5 +1,5 @@
 import type { InstanceType } from '@clerk/types';
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { SUPPORTED_FAPI_VERSION } from '../constants';
 import { createFapiClient } from '../fapiClient';
@@ -64,7 +64,7 @@ beforeAll(() => {
 });
 
 beforeEach(() => {
- (global.fetch as vi.Mock).mockClear();
+ (global.fetch as Mock).mockClear();
 });
 
 afterAll(() => {
@@ -183,33 +183,33 @@ describe('request', () => {
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `https://clerk.example.com/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('invokes global.fetch with proxy', async () => {
  await fapiClientWithProxy.request({
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `${proxyUrl}/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('returns array response as array', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  headers: {
  get: vi.fn(() => 'sess_43'),
@@ -226,7 +226,7 @@ describe('request', () => {
  });
 
  it('handles the empty body on 204 response, returning null', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  status: 204,
  json: () => {
@@ -251,4 +251,65 @@ describe('request', () => {
  it.todo('appends the __clerk_db_jwt cookie value to the query string');
  it.todo('sets the __clerk_db_jwt cookie from the response Clerk-Cookie header');
  });
+
+ describe('retry logic', () => {
+ it('does not send retry query parameter on initial request', async () => {
+ await fapiClient.request({
+ path: '/foo',
+ });
+
+ expect(fetch).toHaveBeenCalledWith(expect.not.stringMatching(/_clerk_retry_attempt=/), expect.any(Object));
+ });
+
+ it('sends retry query parameter on retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount === 1) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=1/);
+ });
+
+ it('increments retry query parameter on multiple retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount <= 2) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+
+ const thirdCall = (fetch as Mock).mock.calls[2];
+ expect(thirdCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+ });
+ });
 });

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

@@ -227,7 +227,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // avoid triggering a CORS OPTION request as it currently breaks cookie dropping in Safari.
  const overwrittenRequestMethod = method === 'GET' ? 'GET' : 'POST';
  let response: Response;
- const urlStr = requestInit.url.toString();
+ const url = requestInit.url;
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
  method: overwrittenRequestMethod,
@@ -237,7 +237,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response = await retry(() => fetch(urlStr, fetchOpts), {
+ response = await retry(() => fetch(url, fetchOpts), {
  // This retry handles only network errors, not 4xx or 5xx responses,
  // so we want to try once immediately to handle simple network blips.
  // Since fapiClient is responsible for the network layer only,
@@ -250,11 +250,17 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // We want to retry only GET requests, as other methods are not idempotent.
  return overwrittenRequestMethod === 'GET' && iterations < maxTries;
  },
+ onBeforeRetry: (iteration: number): void => {
+ // Add the retry attempt to the query string params.
+ // We use params to keep the request simple for CORS.
+ url.searchParams.set('_clerk_retry_attempt', iteration.toString());
+ },
  });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }
  } catch (e) {
+ const urlStr = url.toString();
  debugLogger.error('network error', { error: e, url: urlStr, method }, 'fapiClient');
  clerkNetworkError(urlStr, e);
  }

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

@@ -30,16 +30,15 @@ describe('Token', () => {
  message: '500',
  });
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
 
  describe('with offline browser and network failure', () => {
@@ -67,16 +66,15 @@ describe('Token', () => {
 
  const token = await Token.create('/path/to/tokens');
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
 
  expect(token.getRawString()).toEqual('');
  expect(warnSpy).toBeCalled();
@@ -92,16 +90,15 @@ describe('Token', () => {
  `ClerkJS: Network error at "https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test" - TypeError: Failed to fetch. Please try again.`,
  );
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
  });
  });

packages/shared/src/retry.ts

@@ -3,18 +3,21 @@ type Milliseconds = number;
 type RetryOptions = Partial<{
  /**
  * The initial delay before the first retry.
+ *
  * @default 125
  */
  initialDelay: Milliseconds;
  /**
  * The maximum delay between retries.
  * The delay between retries will never exceed this value.
  * If set to 0, the delay will increase indefinitely.
+ *
  * @default 0
  */
  maxDelayBetweenRetries: Milliseconds;
  /**
  * The multiplier for the exponential backoff.
+ *
  * @default 2
  */
  factor: number;
@@ -23,23 +26,33 @@ type RetryOptions = Partial<{
  * The callback accepts the error that was thrown and the number of iterations.
  * The iterations variable references the number of retries AFTER attempt
  * that caused the error and starts at 1 (as in, this is the 1st, 2nd, nth retry).
+ *
  * @default (error, iterations) => iterations < 5
  */
  shouldRetry: (error: unknown, iterations: number) => boolean;
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
+ *
  * @default false
  */
  retryImmediately: boolean;
  /**
  * If true, the intervals will be multiplied by a factor in the range of [1,2].
+ *
  * @default true
  */
  jitter: boolean;
+
+ /**
+ * A callback that is invoked before each retry attempt.
+ * The callback receives the iteration number (starting from 1 for the first retry).
+ * This can be used to modify request parameters, add headers, etc.
+ */
+ onBeforeRetry?: (iteration: number) => void | Promise<void>;
 }>;
 
-const defaultOptions: Required<RetryOptions> = {
+const defaultOptions = {
  initialDelay: 125,
  maxDelayBetweenRetries: 0,
  factor: 2,
@@ -81,7 +94,7 @@ const createExponentialDelayAsyncFn = (
  */
 export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOptions = {}): Promise<T> => {
  let iterations = 0;
- const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter } = {
+ const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter, onBeforeRetry } = {
  ...defaultOptions,
  ...options,
  };
@@ -101,6 +114,11 @@ export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOpt
  if (!shouldRetry(e, iterations)) {
  throw e;
  }
+
+ if (onBeforeRetry) {
+ await onBeforeRetry(iterations);
+ }
+
  if (retryImmediately && iterations === 1) {
  await sleep(applyJitter(RETRY_IMMEDIATELY_DELAY, jitter));
  } else {

.changeset/poor-memes-wish.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add retry attempt tracking to FAPI client GET requests
+
+The FAPI client now adds a `_clerk_retry_attempt` query parameter to retry attempts for GET requests, allowing servers to track and handle retry scenarios appropriately. This parameter is only added during retry attempts, not on the initial request.

packages/clerk-js/src/core/__tests__/fapiClient.spec.ts

@@ -1,5 +1,5 @@
 import type { InstanceType } from '@clerk/types';
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { SUPPORTED_FAPI_VERSION } from '../constants';
 import { createFapiClient } from '../fapiClient';
@@ -64,7 +64,7 @@ beforeAll(() => {
 });
 
 beforeEach(() => {
- (global.fetch as vi.Mock).mockClear();
+ (global.fetch as Mock).mockClear();
 });
 
 afterAll(() => {
@@ -183,33 +183,33 @@ describe('request', () => {
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `https://clerk.example.com/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('invokes global.fetch with proxy', async () => {
  await fapiClientWithProxy.request({
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `${proxyUrl}/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('returns array response as array', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  headers: {
  get: vi.fn(() => 'sess_43'),
@@ -226,7 +226,7 @@ describe('request', () => {
  });
 
  it('handles the empty body on 204 response, returning null', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  status: 204,
  json: () => {
@@ -251,4 +251,65 @@ describe('request', () => {
  it.todo('appends the __clerk_db_jwt cookie value to the query string');
  it.todo('sets the __clerk_db_jwt cookie from the response Clerk-Cookie header');
  });
+
+ describe('retry logic', () => {
+ it('does not send retry query parameter on initial request', async () => {
+ await fapiClient.request({
+ path: '/foo',
+ });
+
+ expect(fetch).toHaveBeenCalledWith(expect.not.stringMatching(/_clerk_retry_attempt=/), expect.any(Object));
+ });
+
+ it('sends retry query parameter on retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount === 1) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=1/);
+ });
+
+ it('increments retry query parameter on multiple retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount <= 2) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+
+ const thirdCall = (fetch as Mock).mock.calls[2];
+ expect(thirdCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+ });
+ });
 });

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

@@ -227,7 +227,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // avoid triggering a CORS OPTION request as it currently breaks cookie dropping in Safari.
  const overwrittenRequestMethod = method === 'GET' ? 'GET' : 'POST';
  let response: Response;
- const urlStr = requestInit.url.toString();
+ const url = requestInit.url;
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
  method: overwrittenRequestMethod,
@@ -237,7 +237,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response = await retry(() => fetch(urlStr, fetchOpts), {
+ response = await retry(() => fetch(url, fetchOpts), {
  // This retry handles only network errors, not 4xx or 5xx responses,
  // so we want to try once immediately to handle simple network blips.
  // Since fapiClient is responsible for the network layer only,
@@ -250,11 +250,17 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // We want to retry only GET requests, as other methods are not idempotent.
  return overwrittenRequestMethod === 'GET' && iterations < maxTries;
  },
+ onBeforeRetry: (iteration: number): void => {
+ // Add the retry attempt to the query string params.
+ // We use params to keep the request simple for CORS.
+ url.searchParams.set('_clerk_retry_attempt', iteration.toString());
+ },
  });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }
  } catch (e) {
+ const urlStr = url.toString();
  debugLogger.error('network error', { error: e, url: urlStr, method }, 'fapiClient');
  clerkNetworkError(urlStr, e);
  }

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

@@ -30,16 +30,15 @@ describe('Token', () => {
  message: '500',
  });
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
 
  describe('with offline browser and network failure', () => {
@@ -67,16 +66,15 @@ describe('Token', () => {
 
  const token = await Token.create('/path/to/tokens');
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
 
  expect(token.getRawString()).toEqual('');
  expect(warnSpy).toBeCalled();
@@ -92,16 +90,15 @@ describe('Token', () => {
  `ClerkJS: Network error at "https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test" - TypeError: Failed to fetch. Please try again.`,
  );
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
  });
  });

packages/shared/src/retry.ts

@@ -3,18 +3,21 @@ type Milliseconds = number;
 type RetryOptions = Partial<{
  /**
  * The initial delay before the first retry.
+ *
  * @default 125
  */
  initialDelay: Milliseconds;
  /**
  * The maximum delay between retries.
  * The delay between retries will never exceed this value.
  * If set to 0, the delay will increase indefinitely.
+ *
  * @default 0
  */
  maxDelayBetweenRetries: Milliseconds;
  /**
  * The multiplier for the exponential backoff.
+ *
  * @default 2
  */
  factor: number;
@@ -23,23 +26,33 @@ type RetryOptions = Partial<{
  * The callback accepts the error that was thrown and the number of iterations.
  * The iterations variable references the number of retries AFTER attempt
  * that caused the error and starts at 1 (as in, this is the 1st, 2nd, nth retry).
+ *
  * @default (error, iterations) => iterations < 5
  */
  shouldRetry: (error: unknown, iterations: number) => boolean;
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
+ *
  * @default false
  */
  retryImmediately: boolean;
  /**
  * If true, the intervals will be multiplied by a factor in the range of [1,2].
+ *
  * @default true
  */
  jitter: boolean;
+
+ /**
+ * A callback that is invoked before each retry attempt.
+ * The callback receives the iteration number (starting from 1 for the first retry).
+ * This can be used to modify request parameters, add headers, etc.
+ */
+ onBeforeRetry?: (iteration: number) => void | Promise<void>;
 }>;
 
-const defaultOptions: Required<RetryOptions> = {
+const defaultOptions = {
  initialDelay: 125,
  maxDelayBetweenRetries: 0,
  factor: 2,
@@ -81,7 +94,7 @@ const createExponentialDelayAsyncFn = (
  */
 export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOptions = {}): Promise<T> => {
  let iterations = 0;
- const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter } = {
+ const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter, onBeforeRetry } = {
  ...defaultOptions,
  ...options,
  };
@@ -101,6 +114,11 @@ export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOpt
  if (!shouldRetry(e, iterations)) {
  throw e;
  }
+
+ if (onBeforeRetry) {
+ await onBeforeRetry(iterations);
+ }
+
  if (retryImmediately && iterations === 1) {
  await sleep(applyJitter(RETRY_IMMEDIATELY_DELAY, jitter));
  } else {

.changeset/poor-memes-wish.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add retry attempt tracking to FAPI client GET requests
+
+The FAPI client now adds a `_clerk_retry_attempt` query parameter to retry attempts for GET requests, allowing servers to track and handle retry scenarios appropriately. This parameter is only added during retry attempts, not on the initial request.

packages/clerk-js/src/core/__tests__/fapiClient.spec.ts

@@ -1,5 +1,5 @@
 import type { InstanceType } from '@clerk/types';
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { SUPPORTED_FAPI_VERSION } from '../constants';
 import { createFapiClient } from '../fapiClient';
@@ -64,7 +64,7 @@ beforeAll(() => {
 });
 
 beforeEach(() => {
- (global.fetch as vi.Mock).mockClear();
+ (global.fetch as Mock).mockClear();
 });
 
 afterAll(() => {
@@ -183,33 +183,33 @@ describe('request', () => {
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `https://clerk.example.com/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('invokes global.fetch with proxy', async () => {
  await fapiClientWithProxy.request({
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `${proxyUrl}/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('returns array response as array', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  headers: {
  get: vi.fn(() => 'sess_43'),
@@ -226,7 +226,7 @@ describe('request', () => {
  });
 
  it('handles the empty body on 204 response, returning null', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  status: 204,
  json: () => {
@@ -251,4 +251,65 @@ describe('request', () => {
  it.todo('appends the __clerk_db_jwt cookie value to the query string');
  it.todo('sets the __clerk_db_jwt cookie from the response Clerk-Cookie header');
  });
+
+ describe('retry logic', () => {
+ it('does not send retry query parameter on initial request', async () => {
+ await fapiClient.request({
+ path: '/foo',
+ });
+
+ expect(fetch).toHaveBeenCalledWith(expect.not.stringMatching(/_clerk_retry_attempt=/), expect.any(Object));
+ });
+
+ it('sends retry query parameter on retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount === 1) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=1/);
+ });
+
+ it('increments retry query parameter on multiple retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount <= 2) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+
+ const thirdCall = (fetch as Mock).mock.calls[2];
+ expect(thirdCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+ });
+ });
 });

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

@@ -227,7 +227,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // avoid triggering a CORS OPTION request as it currently breaks cookie dropping in Safari.
  const overwrittenRequestMethod = method === 'GET' ? 'GET' : 'POST';
  let response: Response;
- const urlStr = requestInit.url.toString();
+ const url = requestInit.url;
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
  method: overwrittenRequestMethod,
@@ -237,7 +237,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response = await retry(() => fetch(urlStr, fetchOpts), {
+ response = await retry(() => fetch(url, fetchOpts), {
  // This retry handles only network errors, not 4xx or 5xx responses,
  // so we want to try once immediately to handle simple network blips.
  // Since fapiClient is responsible for the network layer only,
@@ -250,11 +250,17 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // We want to retry only GET requests, as other methods are not idempotent.
  return overwrittenRequestMethod === 'GET' && iterations < maxTries;
  },
+ onBeforeRetry: (iteration: number): void => {
+ // Add the retry attempt to the query string params.
+ // We use params to keep the request simple for CORS.
+ url.searchParams.set('_clerk_retry_attempt', iteration.toString());
+ },
  });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }
  } catch (e) {
+ const urlStr = url.toString();
  debugLogger.error('network error', { error: e, url: urlStr, method }, 'fapiClient');
  clerkNetworkError(urlStr, e);
  }

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

@@ -30,16 +30,15 @@ describe('Token', () => {
  message: '500',
  });
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
 
  describe('with offline browser and network failure', () => {
@@ -67,16 +66,15 @@ describe('Token', () => {
 
  const token = await Token.create('/path/to/tokens');
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
 
  expect(token.getRawString()).toEqual('');
  expect(warnSpy).toBeCalled();
@@ -92,16 +90,15 @@ describe('Token', () => {
  `ClerkJS: Network error at "https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test" - TypeError: Failed to fetch. Please try again.`,
  );
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
  });
  });

packages/shared/src/retry.ts

@@ -3,18 +3,21 @@ type Milliseconds = number;
 type RetryOptions = Partial<{
  /**
  * The initial delay before the first retry.
+ *
  * @default 125
  */
  initialDelay: Milliseconds;
  /**
  * The maximum delay between retries.
  * The delay between retries will never exceed this value.
  * If set to 0, the delay will increase indefinitely.
+ *
  * @default 0
  */
  maxDelayBetweenRetries: Milliseconds;
  /**
  * The multiplier for the exponential backoff.
+ *
  * @default 2
  */
  factor: number;
@@ -23,23 +26,33 @@ type RetryOptions = Partial<{
  * The callback accepts the error that was thrown and the number of iterations.
  * The iterations variable references the number of retries AFTER attempt
  * that caused the error and starts at 1 (as in, this is the 1st, 2nd, nth retry).
+ *
  * @default (error, iterations) => iterations < 5
  */
  shouldRetry: (error: unknown, iterations: number) => boolean;
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
+ *
  * @default false
  */
  retryImmediately: boolean;
  /**
  * If true, the intervals will be multiplied by a factor in the range of [1,2].
+ *
  * @default true
  */
  jitter: boolean;
+
+ /**
+ * A callback that is invoked before each retry attempt.
+ * The callback receives the iteration number (starting from 1 for the first retry).
+ * This can be used to modify request parameters, add headers, etc.
+ */
+ onBeforeRetry?: (iteration: number) => void | Promise<void>;
 }>;
 
-const defaultOptions: Required<RetryOptions> = {
+const defaultOptions = {
  initialDelay: 125,
  maxDelayBetweenRetries: 0,
  factor: 2,
@@ -81,7 +94,7 @@ const createExponentialDelayAsyncFn = (
  */
 export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOptions = {}): Promise<T> => {
  let iterations = 0;
- const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter } = {
+ const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter, onBeforeRetry } = {
  ...defaultOptions,
  ...options,
  };
@@ -101,6 +114,11 @@ export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOpt
  if (!shouldRetry(e, iterations)) {
  throw e;
  }
+
+ if (onBeforeRetry) {
+ await onBeforeRetry(iterations);
+ }
+
  if (retryImmediately && iterations === 1) {
  await sleep(applyJitter(RETRY_IMMEDIATELY_DELAY, jitter));
  } else {

.changeset/poor-memes-wish.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add retry attempt tracking to FAPI client GET requests
+
+The FAPI client now adds a `_clerk_retry_attempt` query parameter to retry attempts for GET requests, allowing servers to track and handle retry scenarios appropriately. This parameter is only added during retry attempts, not on the initial request.

packages/clerk-js/src/core/__tests__/fapiClient.spec.ts

@@ -1,5 +1,5 @@
 import type { InstanceType } from '@clerk/types';
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { SUPPORTED_FAPI_VERSION } from '../constants';
 import { createFapiClient } from '../fapiClient';
@@ -64,7 +64,7 @@ beforeAll(() => {
 });
 
 beforeEach(() => {
- (global.fetch as vi.Mock).mockClear();
+ (global.fetch as Mock).mockClear();
 });
 
 afterAll(() => {
@@ -183,33 +183,33 @@ describe('request', () => {
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `https://clerk.example.com/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('invokes global.fetch with proxy', async () => {
  await fapiClientWithProxy.request({
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `${proxyUrl}/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('returns array response as array', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  headers: {
  get: vi.fn(() => 'sess_43'),
@@ -226,7 +226,7 @@ describe('request', () => {
  });
 
  it('handles the empty body on 204 response, returning null', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  status: 204,
  json: () => {
@@ -251,4 +251,65 @@ describe('request', () => {
  it.todo('appends the __clerk_db_jwt cookie value to the query string');
  it.todo('sets the __clerk_db_jwt cookie from the response Clerk-Cookie header');
  });
+
+ describe('retry logic', () => {
+ it('does not send retry query parameter on initial request', async () => {
+ await fapiClient.request({
+ path: '/foo',
+ });
+
+ expect(fetch).toHaveBeenCalledWith(expect.not.stringMatching(/_clerk_retry_attempt=/), expect.any(Object));
+ });
+
+ it('sends retry query parameter on retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount === 1) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=1/);
+ });
+
+ it('increments retry query parameter on multiple retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount <= 2) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+
+ const thirdCall = (fetch as Mock).mock.calls[2];
+ expect(thirdCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+ });
+ });
 });

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

@@ -227,7 +227,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // avoid triggering a CORS OPTION request as it currently breaks cookie dropping in Safari.
  const overwrittenRequestMethod = method === 'GET' ? 'GET' : 'POST';
  let response: Response;
- const urlStr = requestInit.url.toString();
+ const url = requestInit.url;
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
  method: overwrittenRequestMethod,
@@ -237,7 +237,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response = await retry(() => fetch(urlStr, fetchOpts), {
+ response = await retry(() => fetch(url, fetchOpts), {
  // This retry handles only network errors, not 4xx or 5xx responses,
  // so we want to try once immediately to handle simple network blips.
  // Since fapiClient is responsible for the network layer only,
@@ -250,11 +250,17 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // We want to retry only GET requests, as other methods are not idempotent.
  return overwrittenRequestMethod === 'GET' && iterations < maxTries;
  },
+ onBeforeRetry: (iteration: number): void => {
+ // Add the retry attempt to the query string params.
+ // We use params to keep the request simple for CORS.
+ url.searchParams.set('_clerk_retry_attempt', iteration.toString());
+ },
  });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }
  } catch (e) {
+ const urlStr = url.toString();
  debugLogger.error('network error', { error: e, url: urlStr, method }, 'fapiClient');
  clerkNetworkError(urlStr, e);
  }

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

@@ -30,16 +30,15 @@ describe('Token', () => {
  message: '500',
  });
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
 
  describe('with offline browser and network failure', () => {
@@ -67,16 +66,15 @@ describe('Token', () => {
 
  const token = await Token.create('/path/to/tokens');
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
 
  expect(token.getRawString()).toEqual('');
  expect(warnSpy).toBeCalled();
@@ -92,16 +90,15 @@ describe('Token', () => {
  `ClerkJS: Network error at "https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test" - TypeError: Failed to fetch. Please try again.`,
  );
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
  });
  });

packages/shared/src/retry.ts

@@ -3,18 +3,21 @@ type Milliseconds = number;
 type RetryOptions = Partial<{
  /**
  * The initial delay before the first retry.
+ *
  * @default 125
  */
  initialDelay: Milliseconds;
  /**
  * The maximum delay between retries.
  * The delay between retries will never exceed this value.
  * If set to 0, the delay will increase indefinitely.
+ *
  * @default 0
  */
  maxDelayBetweenRetries: Milliseconds;
  /**
  * The multiplier for the exponential backoff.
+ *
  * @default 2
  */
  factor: number;
@@ -23,23 +26,33 @@ type RetryOptions = Partial<{
  * The callback accepts the error that was thrown and the number of iterations.
  * The iterations variable references the number of retries AFTER attempt
  * that caused the error and starts at 1 (as in, this is the 1st, 2nd, nth retry).
+ *
  * @default (error, iterations) => iterations < 5
  */
  shouldRetry: (error: unknown, iterations: number) => boolean;
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
+ *
  * @default false
  */
  retryImmediately: boolean;
  /**
  * If true, the intervals will be multiplied by a factor in the range of [1,2].
+ *
  * @default true
  */
  jitter: boolean;
+
+ /**
+ * A callback that is invoked before each retry attempt.
+ * The callback receives the iteration number (starting from 1 for the first retry).
+ * This can be used to modify request parameters, add headers, etc.
+ */
+ onBeforeRetry?: (iteration: number) => void | Promise<void>;
 }>;
 
-const defaultOptions: Required<RetryOptions> = {
+const defaultOptions = {
  initialDelay: 125,
  maxDelayBetweenRetries: 0,
  factor: 2,
@@ -81,7 +94,7 @@ const createExponentialDelayAsyncFn = (
  */
 export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOptions = {}): Promise<T> => {
  let iterations = 0;
- const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter } = {
+ const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter, onBeforeRetry } = {
  ...defaultOptions,
  ...options,
  };
@@ -101,6 +114,11 @@ export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOpt
  if (!shouldRetry(e, iterations)) {
  throw e;
  }
+
+ if (onBeforeRetry) {
+ await onBeforeRetry(iterations);
+ }
+
  if (retryImmediately && iterations === 1) {
  await sleep(applyJitter(RETRY_IMMEDIATELY_DELAY, jitter));
  } else {

.changeset/poor-memes-wish.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add retry attempt tracking to FAPI client GET requests
+
+The FAPI client now adds a `_clerk_retry_attempt` query parameter to retry attempts for GET requests, allowing servers to track and handle retry scenarios appropriately. This parameter is only added during retry attempts, not on the initial request.

packages/clerk-js/src/core/__tests__/fapiClient.spec.ts

@@ -1,5 +1,5 @@
 import type { InstanceType } from '@clerk/types';
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { SUPPORTED_FAPI_VERSION } from '../constants';
 import { createFapiClient } from '../fapiClient';
@@ -64,7 +64,7 @@ beforeAll(() => {
 });
 
 beforeEach(() => {
- (global.fetch as vi.Mock).mockClear();
+ (global.fetch as Mock).mockClear();
 });
 
 afterAll(() => {
@@ -183,33 +183,33 @@ describe('request', () => {
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `https://clerk.example.com/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('invokes global.fetch with proxy', async () => {
  await fapiClientWithProxy.request({
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `${proxyUrl}/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('returns array response as array', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  headers: {
  get: vi.fn(() => 'sess_43'),
@@ -226,7 +226,7 @@ describe('request', () => {
  });
 
  it('handles the empty body on 204 response, returning null', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  status: 204,
  json: () => {
@@ -251,4 +251,65 @@ describe('request', () => {
  it.todo('appends the __clerk_db_jwt cookie value to the query string');
  it.todo('sets the __clerk_db_jwt cookie from the response Clerk-Cookie header');
  });
+
+ describe('retry logic', () => {
+ it('does not send retry query parameter on initial request', async () => {
+ await fapiClient.request({
+ path: '/foo',
+ });
+
+ expect(fetch).toHaveBeenCalledWith(expect.not.stringMatching(/_clerk_retry_attempt=/), expect.any(Object));
+ });
+
+ it('sends retry query parameter on retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount === 1) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=1/);
+ });
+
+ it('increments retry query parameter on multiple retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount <= 2) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+
+ const thirdCall = (fetch as Mock).mock.calls[2];
+ expect(thirdCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+ });
+ });
 });

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

@@ -227,7 +227,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // avoid triggering a CORS OPTION request as it currently breaks cookie dropping in Safari.
  const overwrittenRequestMethod = method === 'GET' ? 'GET' : 'POST';
  let response: Response;
- const urlStr = requestInit.url.toString();
+ const url = requestInit.url;
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
  method: overwrittenRequestMethod,
@@ -237,7 +237,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response = await retry(() => fetch(urlStr, fetchOpts), {
+ response = await retry(() => fetch(url, fetchOpts), {
  // This retry handles only network errors, not 4xx or 5xx responses,
  // so we want to try once immediately to handle simple network blips.
  // Since fapiClient is responsible for the network layer only,
@@ -250,11 +250,17 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // We want to retry only GET requests, as other methods are not idempotent.
  return overwrittenRequestMethod === 'GET' && iterations < maxTries;
  },
+ onBeforeRetry: (iteration: number): void => {
+ // Add the retry attempt to the query string params.
+ // We use params to keep the request simple for CORS.
+ url.searchParams.set('_clerk_retry_attempt', iteration.toString());
+ },
  });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }
  } catch (e) {
+ const urlStr = url.toString();
  debugLogger.error('network error', { error: e, url: urlStr, method }, 'fapiClient');
  clerkNetworkError(urlStr, e);
  }

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

@@ -30,16 +30,15 @@ describe('Token', () => {
  message: '500',
  });
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
 
  describe('with offline browser and network failure', () => {
@@ -67,16 +66,15 @@ describe('Token', () => {
 
  const token = await Token.create('/path/to/tokens');
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
 
  expect(token.getRawString()).toEqual('');
  expect(warnSpy).toBeCalled();
@@ -92,16 +90,15 @@ describe('Token', () => {
  `ClerkJS: Network error at "https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test" - TypeError: Failed to fetch. Please try again.`,
  );
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
  });
  });

packages/shared/src/retry.ts

@@ -3,18 +3,21 @@ type Milliseconds = number;
 type RetryOptions = Partial<{
  /**
  * The initial delay before the first retry.
+ *
  * @default 125
  */
  initialDelay: Milliseconds;
  /**
  * The maximum delay between retries.
  * The delay between retries will never exceed this value.
  * If set to 0, the delay will increase indefinitely.
+ *
  * @default 0
  */
  maxDelayBetweenRetries: Milliseconds;
  /**
  * The multiplier for the exponential backoff.
+ *
  * @default 2
  */
  factor: number;
@@ -23,23 +26,33 @@ type RetryOptions = Partial<{
  * The callback accepts the error that was thrown and the number of iterations.
  * The iterations variable references the number of retries AFTER attempt
  * that caused the error and starts at 1 (as in, this is the 1st, 2nd, nth retry).
+ *
  * @default (error, iterations) => iterations < 5
  */
  shouldRetry: (error: unknown, iterations: number) => boolean;
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
+ *
  * @default false
  */
  retryImmediately: boolean;
  /**
  * If true, the intervals will be multiplied by a factor in the range of [1,2].
+ *
  * @default true
  */
  jitter: boolean;
+
+ /**
+ * A callback that is invoked before each retry attempt.
+ * The callback receives the iteration number (starting from 1 for the first retry).
+ * This can be used to modify request parameters, add headers, etc.
+ */
+ onBeforeRetry?: (iteration: number) => void | Promise<void>;
 }>;
 
-const defaultOptions: Required<RetryOptions> = {
+const defaultOptions = {
  initialDelay: 125,
  maxDelayBetweenRetries: 0,
  factor: 2,
@@ -81,7 +94,7 @@ const createExponentialDelayAsyncFn = (
  */
 export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOptions = {}): Promise<T> => {
  let iterations = 0;
- const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter } = {
+ const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter, onBeforeRetry } = {
  ...defaultOptions,
  ...options,
  };
@@ -101,6 +114,11 @@ export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOpt
  if (!shouldRetry(e, iterations)) {
  throw e;
  }
+
+ if (onBeforeRetry) {
+ await onBeforeRetry(iterations);
+ }
+
  if (retryImmediately && iterations === 1) {
  await sleep(applyJitter(RETRY_IMMEDIATELY_DELAY, jitter));
  } else {

.changeset/poor-memes-wish.md

@@ -0,0 +1,8 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Add retry attempt tracking to FAPI client GET requests
+
+The FAPI client now adds a `_clerk_retry_attempt` query parameter to retry attempts for GET requests, allowing servers to track and handle retry scenarios appropriately. This parameter is only added during retry attempts, not on the initial request.

packages/clerk-js/src/core/__tests__/fapiClient.spec.ts

@@ -1,5 +1,5 @@
 import type { InstanceType } from '@clerk/types';
-import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, type Mock, vi } from 'vitest';
 
 import { SUPPORTED_FAPI_VERSION } from '../constants';
 import { createFapiClient } from '../fapiClient';
@@ -64,7 +64,7 @@ beforeAll(() => {
 });
 
 beforeEach(() => {
- (global.fetch as vi.Mock).mockClear();
+ (global.fetch as Mock).mockClear();
 });
 
 afterAll(() => {
@@ -183,33 +183,33 @@ describe('request', () => {
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `https://clerk.example.com/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('invokes global.fetch with proxy', async () => {
  await fapiClientWithProxy.request({
  path: '/foo',
  });
 
- expect(fetch).toHaveBeenCalledWith(
+ const fetchCall = (fetch as Mock).mock.calls[0];
+ expect(fetchCall[0].toString()).toBe(
  `${proxyUrl}/v1/foo?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test&_clerk_session_id=sess_1qq9oy5GiNHxdR2XWU6gG6mIcBX`,
- expect.objectContaining({
- credentials: 'include',
- method: 'GET',
- path: '/foo',
- }),
  );
+ expect(fetchCall[1]).toMatchObject({
+ credentials: 'include',
+ method: 'GET',
+ });
  });
 
  it('returns array response as array', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  headers: {
  get: vi.fn(() => 'sess_43'),
@@ -226,7 +226,7 @@ describe('request', () => {
  });
 
  it('handles the empty body on 204 response, returning null', async () => {
- (global.fetch as vi.Mock).mockResolvedValueOnce(
+ (global.fetch as Mock).mockResolvedValueOnce(
  Promise.resolve<RecursivePartial<Response>>({
  status: 204,
  json: () => {
@@ -251,4 +251,65 @@ describe('request', () => {
  it.todo('appends the __clerk_db_jwt cookie value to the query string');
  it.todo('sets the __clerk_db_jwt cookie from the response Clerk-Cookie header');
  });
+
+ describe('retry logic', () => {
+ it('does not send retry query parameter on initial request', async () => {
+ await fapiClient.request({
+ path: '/foo',
+ });
+
+ expect(fetch).toHaveBeenCalledWith(expect.not.stringMatching(/_clerk_retry_attempt=/), expect.any(Object));
+ });
+
+ it('sends retry query parameter on retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount === 1) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=1/);
+ });
+
+ it('increments retry query parameter on multiple retry attempts', async () => {
+ let callCount = 0;
+ (global.fetch as Mock).mockImplementation(() => {
+ callCount++;
+ if (callCount <= 2) {
+ return Promise.reject(new Error('Network error'));
+ }
+ return Promise.resolve<RecursivePartial<Response>>({
+ headers: {
+ get: vi.fn(() => 'sess_43'),
+ },
+ json: () => Promise.resolve({ foo: 42 }),
+ });
+ });
+
+ await fapiClient.request({
+ path: '/foo',
+ method: 'GET',
+ });
+
+ const secondCall = (fetch as Mock).mock.calls[1];
+ expect(secondCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+
+ const thirdCall = (fetch as Mock).mock.calls[2];
+ expect(thirdCall[0].toString()).toMatch(/_clerk_retry_attempt=2/);
+ });
+ });
 });

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

@@ -227,7 +227,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // avoid triggering a CORS OPTION request as it currently breaks cookie dropping in Safari.
  const overwrittenRequestMethod = method === 'GET' ? 'GET' : 'POST';
  let response: Response;
- const urlStr = requestInit.url.toString();
+ const url = requestInit.url;
  const fetchOpts: FapiRequestInit = {
  ...requestInit,
  method: overwrittenRequestMethod,
@@ -237,7 +237,7 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  try {
  if (beforeRequestCallbacksResult) {
  const maxTries = requestOptions?.fetchMaxTries ?? (isBrowserOnline() ? 4 : 11);
- response = await retry(() => fetch(urlStr, fetchOpts), {
+ response = await retry(() => fetch(url, fetchOpts), {
  // This retry handles only network errors, not 4xx or 5xx responses,
  // so we want to try once immediately to handle simple network blips.
  // Since fapiClient is responsible for the network layer only,
@@ -250,11 +250,17 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
  // We want to retry only GET requests, as other methods are not idempotent.
  return overwrittenRequestMethod === 'GET' && iterations < maxTries;
  },
+ onBeforeRetry: (iteration: number): void => {
+ // Add the retry attempt to the query string params.
+ // We use params to keep the request simple for CORS.
+ url.searchParams.set('_clerk_retry_attempt', iteration.toString());
+ },
  });
  } else {
  response = new Response('{}', requestInit); // Mock an empty json response
  }
  } catch (e) {
+ const urlStr = url.toString();
  debugLogger.error('network error', { error: e, url: urlStr, method }, 'fapiClient');
  clerkNetworkError(urlStr, e);
  }

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

@@ -30,16 +30,15 @@ describe('Token', () => {
  message: '500',
  });
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
 
  describe('with offline browser and network failure', () => {
@@ -67,16 +66,15 @@ describe('Token', () => {
 
  const token = await Token.create('/path/to/tokens');
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
 
  expect(token.getRawString()).toEqual('');
  expect(warnSpy).toBeCalled();
@@ -92,16 +90,15 @@ describe('Token', () => {
  `ClerkJS: Network error at "https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test" - TypeError: Failed to fetch. Please try again.`,
  );
 
- expect(global.fetch).toHaveBeenCalledWith(
- `https://clerk.example.com/v1/path/to/tokens?__clerk_api_version=${SUPPORTED_FAPI_VERSION}&_clerk_js_version=test`,
- // TODO(dimkl): omit extra params from fetch request (eg path, url) - remove expect.objectContaining
- expect.objectContaining({
- method: 'POST',
- body: '',
- credentials: 'include',
- headers: new Headers(),
- }),
- );
+ expect(global.fetch).toHaveBeenCalledTimes(1);
+ const [url, options] = (global.fetch as Mock).mock.calls[0];
+ expect(url.toString()).toContain('https://clerk.example.com/v1/path/to/tokens');
+ expect(options).toMatchObject({
+ method: 'POST',
+ body: '',
+ credentials: 'include',
+ headers: expect.any(Headers),
+ });
  });
  });
  });

packages/shared/src/retry.ts

@@ -3,18 +3,21 @@ type Milliseconds = number;
 type RetryOptions = Partial<{
  /**
  * The initial delay before the first retry.
+ *
  * @default 125
  */
  initialDelay: Milliseconds;
  /**
  * The maximum delay between retries.
  * The delay between retries will never exceed this value.
  * If set to 0, the delay will increase indefinitely.
+ *
  * @default 0
  */
  maxDelayBetweenRetries: Milliseconds;
  /**
  * The multiplier for the exponential backoff.
+ *
  * @default 2
  */
  factor: number;
@@ -23,23 +26,33 @@ type RetryOptions = Partial<{
  * The callback accepts the error that was thrown and the number of iterations.
  * The iterations variable references the number of retries AFTER attempt
  * that caused the error and starts at 1 (as in, this is the 1st, 2nd, nth retry).
+ *
  * @default (error, iterations) => iterations < 5
  */
  shouldRetry: (error: unknown, iterations: number) => boolean;
  /**
  * Controls whether the helper should retry the operation immediately once before applying exponential backoff.
  * The delay for the immediate retry is 100ms.
+ *
  * @default false
  */
  retryImmediately: boolean;
  /**
  * If true, the intervals will be multiplied by a factor in the range of [1,2].
+ *
  * @default true
  */
  jitter: boolean;
+
+ /**
+ * A callback that is invoked before each retry attempt.
+ * The callback receives the iteration number (starting from 1 for the first retry).
+ * This can be used to modify request parameters, add headers, etc.
+ */
+ onBeforeRetry?: (iteration: number) => void | Promise<void>;
 }>;
 
-const defaultOptions: Required<RetryOptions> = {
+const defaultOptions = {
  initialDelay: 125,
  maxDelayBetweenRetries: 0,
  factor: 2,
@@ -81,7 +94,7 @@ const createExponentialDelayAsyncFn = (
  */
 export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOptions = {}): Promise<T> => {
  let iterations = 0;
- const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter } = {
+ const { shouldRetry, initialDelay, maxDelayBetweenRetries, factor, retryImmediately, jitter, onBeforeRetry } = {
  ...defaultOptions,
  ...options,
  };
@@ -101,6 +114,11 @@ export const retry = async <T>(callback: () => T | Promise<T>, options: RetryOpt
  if (!shouldRetry(e, iterations)) {
  throw e;
  }
+
+ if (onBeforeRetry) {
+ await onBeforeRetry(iterations);
+ }
+
  if (retryImmediately && iterations === 1) {
  await sleep(applyJitter(RETRY_IMMEDIATELY_DELAY, jitter));
  } else {