feat(shared): Add opt-out support for SDK telemetry

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

@@ -173,7 +173,7 @@ export default class Clerk implements ClerkInterface {
  #devBrowserHandler: DevBrowserHandler | null = null;
  #environment?: EnvironmentResource | null;
  #fapiClient: FapiClient;
- #telemetry: TelemetryCollector;
+ #telemetry?: TelemetryCollector;
  #instanceType: InstanceType;
  #isReady = false;
 
@@ -308,12 +308,6 @@ export default class Clerk implements ClerkInterface {
  this.#instanceType = instanceType;
  }
  this.#fapiClient = createFapiClient(this);
- this.#telemetry = new TelemetryCollector({
- clerkVersion: Clerk.version,
- verbose: true,
- samplingRate: 1,
- publishableKey: key,
- });
  BaseResource.clerk = this;
  }
 
@@ -331,6 +325,19 @@ export default class Clerk implements ClerkInterface {
  ...options,
  };
 
+ if (this.#options.sdkMetadata) {
+ Clerk.sdkMetadata = this.#options.sdkMetadata;
+ }
+
+ this.#telemetry = new TelemetryCollector({
+ clerkVersion: Clerk.version,
+ verbose: true,
+ samplingRate: 1,
+ // @ts-expect-error -- in v5 this will always be defined
+ publishableKey: this.publishableKey,
+ ...this.#options.telemetry,
+ });
+
  if (this.#options.standardBrowser) {
  this.#isReady = await this.#loadInStandardBrowser();
  } else {

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,8 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
+
 const SDK_METADATA = {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,
@@ -28,6 +30,10 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
  navigate={to => navigate(to)}
  initialState={__clerk_ssr_state || {}}
  sdkMetadata={SDK_METADATA}
+ telemetry={{
+ disabled: TELEMETRY_DISABLED,
+ debug: TELEMETRY_DEBUG,
+ }}
  {...restProps}
  >
  {__clerk_ssr_interstitial_html ? (

packages/gatsby-plugin-clerk/src/constants.ts

@@ -1,4 +1,5 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { isTruthy } from '@clerk/shared/underscore';
 
 export const PUBLISHABLE_KEY = process.env.GATSBY_CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
@@ -7,3 +8,6 @@ export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
 
 export const CLERK_JS = process.env.GATSBY_CLERK_JS;
 export const PROXY_URL = process.env.GATSBY_CLERK_PROXY_URL;
+
+export const TELEMETRY_DISABLED = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DISABLED);
+export const TELEMETRY_DEBUG = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DEBUG);

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,6 +15,10 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
  signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
  afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
  afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+ telemetry: {
+ disabled: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED),
+ debug: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DEBUG),
+ },
  sdkMetadata: {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,

packages/react/src/isomorphicClerk.ts

@@ -132,6 +132,11 @@ export default class IsomorphicClerk {
  this.options = options;
  this.Clerk = Clerk;
  this.mode = inBrowser() ? 'browser' : 'server';
+
+ if (!this.options.sdkMetadata) {
+ this.options.sdkMetadata = SDK_METADATA;
+ }
+
  void this.loadClerkJS();
  }
 
@@ -168,7 +173,6 @@ export default class IsomorphicClerk {
  domain: this.domain,
  } as any);
 
- c.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
  await c.load(this.options);
  } else {
  // Otherwise use the instantiated Clerk object
@@ -195,13 +199,9 @@ export default class IsomorphicClerk {
  throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
-
  await global.Clerk.load(this.options);
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
-
  if (global.Clerk?.loaded || global.Clerk?.isReady()) {
  return this.hydrateClerkJS(global.Clerk);
  }

packages/remix/src/client/RemixClerkProvider.tsx

@@ -56,6 +56,8 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  __afterSignUpUrl,
  __clerkJSUrl,
  __clerkJSVersion,
+ __telemetryDisabled,
+ __telemetryDebug,
  } = clerkState?.__internal_clerk_state || {};
 
  React.useEffect(() => {
@@ -77,6 +79,10 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  afterSignUpUrl: __afterSignUpUrl,
  clerkJSUrl: __clerkJSUrl,
  clerkJSVersion: __clerkJSVersion,
+ telemetry: {
+ disabled: __telemetryDisabled,
+ debug: __telemetryDebug,
+ },
  };
 
  return (

packages/remix/src/client/types.ts

@@ -18,6 +18,8 @@ export type ClerkState = {
  __clerk_debug: any;
  __clerkJSUrl: string | undefined;
  __clerkJSVersion: string | undefined;
+ __telemetryDisabled: boolean | undefined;
+ __telemetryDebug: boolean | undefined;
  };
 };
 

packages/remix/src/ssr/utils.ts

@@ -1,5 +1,6 @@
 import type { AuthObject, RequestState } from '@clerk/backend';
 import { constants, debugRequestState, loadInterstitialFromLocal } from '@clerk/backend';
+import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext, defer } from '@remix-run/server-runtime';
 import { json } from '@remix-run/server-runtime';
 import cookie from 'cookie';
@@ -165,6 +166,8 @@ export function getResponseClerkState(requestState: RequestState, context: AppLo
  __clerk_debug: debugRequestState(requestState),
  __clerkJSUrl: getEnvVariable('CLERK_JS', context),
  __clerkJSVersion: getEnvVariable('CLERK_JS_VERSION', context),
+ __telemetryDisabled: isTruthy(getEnvVariable('CLERK_TELEMETRY_DISABLED', context)),
+ __telemetryDebug: isTruthy(getEnvVariable('CLERK_TELEMETRY_DEBUG', context)),
  });
 
  const headers = observabilityHeadersFromRequestState(requestState);

packages/shared/.gitignore

@@ -1,2 +1,2 @@
-*/
+/*/
 !src/

packages/shared/jest.config.js

@@ -4,6 +4,9 @@ const { name } = require('./package.json');
 const config = {
  displayName: name.replace('@clerk', ''),
  injectGlobals: true,
+ globals: {
+ fetch: global.fetch,
+ },
 
  testEnvironment: 'jsdom',
  roots: ['<rootDir>/src'],

packages/shared/src/__tests__/telemetry.test.ts

@@ -0,0 +1,149 @@
+import { TelemetryCollector } from '../telemetry';
+
+jest.useFakeTimers();
+
+const TEST_PK = 'pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk';
+
+describe('TelemetryCollector', () => {
+ test('does nothing when disabled', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ disabled: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('does nothing when CLERK_TELEMETRY_DISABLED is set', async () => {
+ process.env.CLERK_TELEMETRY_DISABLED = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DISABLED = undefined;
+ });
+
+ test('does not send events when debug is enabled, logs them instead', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ debug: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+ });
+
+ test('enables debug via environment variable', async () => {
+ process.env.CLERK_TELEMETRY_DEBUG = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DEBUG = undefined;
+ });
+
+ test('sends events after a delay when buffer is not full', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('sends events immediately when the buffer limit is reached', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ maxBufferSize: 2,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+ collector.record('TEST_EVENT', {});
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+});

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

@@ -173,7 +173,7 @@ export default class Clerk implements ClerkInterface {
  #devBrowserHandler: DevBrowserHandler | null = null;
  #environment?: EnvironmentResource | null;
  #fapiClient: FapiClient;
- #telemetry: TelemetryCollector;
+ #telemetry?: TelemetryCollector;
  #instanceType: InstanceType;
  #isReady = false;
 
@@ -308,12 +308,6 @@ export default class Clerk implements ClerkInterface {
  this.#instanceType = instanceType;
  }
  this.#fapiClient = createFapiClient(this);
- this.#telemetry = new TelemetryCollector({
- clerkVersion: Clerk.version,
- verbose: true,
- samplingRate: 1,
- publishableKey: key,
- });
  BaseResource.clerk = this;
  }
 
@@ -331,6 +325,19 @@ export default class Clerk implements ClerkInterface {
  ...options,
  };
 
+ if (this.#options.sdkMetadata) {
+ Clerk.sdkMetadata = this.#options.sdkMetadata;
+ }
+
+ this.#telemetry = new TelemetryCollector({
+ clerkVersion: Clerk.version,
+ verbose: true,
+ samplingRate: 1,
+ // @ts-expect-error -- in v5 this will always be defined
+ publishableKey: this.publishableKey,
+ ...this.#options.telemetry,
+ });
+
  if (this.#options.standardBrowser) {
  this.#isReady = await this.#loadInStandardBrowser();
  } else {

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,8 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
+
 const SDK_METADATA = {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,
@@ -28,6 +30,10 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
  navigate={to => navigate(to)}
  initialState={__clerk_ssr_state || {}}
  sdkMetadata={SDK_METADATA}
+ telemetry={{
+ disabled: TELEMETRY_DISABLED,
+ debug: TELEMETRY_DEBUG,
+ }}
  {...restProps}
  >
  {__clerk_ssr_interstitial_html ? (

packages/gatsby-plugin-clerk/src/constants.ts

@@ -1,4 +1,5 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { isTruthy } from '@clerk/shared/underscore';
 
 export const PUBLISHABLE_KEY = process.env.GATSBY_CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
@@ -7,3 +8,6 @@ export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
 
 export const CLERK_JS = process.env.GATSBY_CLERK_JS;
 export const PROXY_URL = process.env.GATSBY_CLERK_PROXY_URL;
+
+export const TELEMETRY_DISABLED = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DISABLED);
+export const TELEMETRY_DEBUG = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DEBUG);

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,6 +15,10 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
  signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
  afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
  afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+ telemetry: {
+ disabled: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED),
+ debug: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DEBUG),
+ },
  sdkMetadata: {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,

packages/react/src/isomorphicClerk.ts

@@ -132,6 +132,11 @@ export default class IsomorphicClerk {
  this.options = options;
  this.Clerk = Clerk;
  this.mode = inBrowser() ? 'browser' : 'server';
+
+ if (!this.options.sdkMetadata) {
+ this.options.sdkMetadata = SDK_METADATA;
+ }
+
  void this.loadClerkJS();
  }
 
@@ -168,7 +173,6 @@ export default class IsomorphicClerk {
  domain: this.domain,
  } as any);
 
- c.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
  await c.load(this.options);
  } else {
  // Otherwise use the instantiated Clerk object
@@ -195,13 +199,9 @@ export default class IsomorphicClerk {
  throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
-
  await global.Clerk.load(this.options);
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
-
  if (global.Clerk?.loaded || global.Clerk?.isReady()) {
  return this.hydrateClerkJS(global.Clerk);
  }

packages/remix/src/client/RemixClerkProvider.tsx

@@ -56,6 +56,8 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  __afterSignUpUrl,
  __clerkJSUrl,
  __clerkJSVersion,
+ __telemetryDisabled,
+ __telemetryDebug,
  } = clerkState?.__internal_clerk_state || {};
 
  React.useEffect(() => {
@@ -77,6 +79,10 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  afterSignUpUrl: __afterSignUpUrl,
  clerkJSUrl: __clerkJSUrl,
  clerkJSVersion: __clerkJSVersion,
+ telemetry: {
+ disabled: __telemetryDisabled,
+ debug: __telemetryDebug,
+ },
  };
 
  return (

packages/remix/src/client/types.ts

@@ -18,6 +18,8 @@ export type ClerkState = {
  __clerk_debug: any;
  __clerkJSUrl: string | undefined;
  __clerkJSVersion: string | undefined;
+ __telemetryDisabled: boolean | undefined;
+ __telemetryDebug: boolean | undefined;
  };
 };
 

packages/remix/src/ssr/utils.ts

@@ -1,5 +1,6 @@
 import type { AuthObject, RequestState } from '@clerk/backend';
 import { constants, debugRequestState, loadInterstitialFromLocal } from '@clerk/backend';
+import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext, defer } from '@remix-run/server-runtime';
 import { json } from '@remix-run/server-runtime';
 import cookie from 'cookie';
@@ -165,6 +166,8 @@ export function getResponseClerkState(requestState: RequestState, context: AppLo
  __clerk_debug: debugRequestState(requestState),
  __clerkJSUrl: getEnvVariable('CLERK_JS', context),
  __clerkJSVersion: getEnvVariable('CLERK_JS_VERSION', context),
+ __telemetryDisabled: isTruthy(getEnvVariable('CLERK_TELEMETRY_DISABLED', context)),
+ __telemetryDebug: isTruthy(getEnvVariable('CLERK_TELEMETRY_DEBUG', context)),
  });
 
  const headers = observabilityHeadersFromRequestState(requestState);

packages/shared/.gitignore

@@ -1,2 +1,2 @@
-*/
+/*/
 !src/

packages/shared/jest.config.js

@@ -4,6 +4,9 @@ const { name } = require('./package.json');
 const config = {
  displayName: name.replace('@clerk', ''),
  injectGlobals: true,
+ globals: {
+ fetch: global.fetch,
+ },
 
  testEnvironment: 'jsdom',
  roots: ['<rootDir>/src'],

packages/shared/src/__tests__/telemetry.test.ts

@@ -0,0 +1,149 @@
+import { TelemetryCollector } from '../telemetry';
+
+jest.useFakeTimers();
+
+const TEST_PK = 'pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk';
+
+describe('TelemetryCollector', () => {
+ test('does nothing when disabled', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ disabled: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('does nothing when CLERK_TELEMETRY_DISABLED is set', async () => {
+ process.env.CLERK_TELEMETRY_DISABLED = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DISABLED = undefined;
+ });
+
+ test('does not send events when debug is enabled, logs them instead', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ debug: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+ });
+
+ test('enables debug via environment variable', async () => {
+ process.env.CLERK_TELEMETRY_DEBUG = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DEBUG = undefined;
+ });
+
+ test('sends events after a delay when buffer is not full', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('sends events immediately when the buffer limit is reached', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ maxBufferSize: 2,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+ collector.record('TEST_EVENT', {});
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+});

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

@@ -173,7 +173,7 @@ export default class Clerk implements ClerkInterface {
  #devBrowserHandler: DevBrowserHandler | null = null;
  #environment?: EnvironmentResource | null;
  #fapiClient: FapiClient;
- #telemetry: TelemetryCollector;
+ #telemetry?: TelemetryCollector;
  #instanceType: InstanceType;
  #isReady = false;
 
@@ -308,12 +308,6 @@ export default class Clerk implements ClerkInterface {
  this.#instanceType = instanceType;
  }
  this.#fapiClient = createFapiClient(this);
- this.#telemetry = new TelemetryCollector({
- clerkVersion: Clerk.version,
- verbose: true,
- samplingRate: 1,
- publishableKey: key,
- });
  BaseResource.clerk = this;
  }
 
@@ -331,6 +325,19 @@ export default class Clerk implements ClerkInterface {
  ...options,
  };
 
+ if (this.#options.sdkMetadata) {
+ Clerk.sdkMetadata = this.#options.sdkMetadata;
+ }
+
+ this.#telemetry = new TelemetryCollector({
+ clerkVersion: Clerk.version,
+ verbose: true,
+ samplingRate: 1,
+ // @ts-expect-error -- in v5 this will always be defined
+ publishableKey: this.publishableKey,
+ ...this.#options.telemetry,
+ });
+
  if (this.#options.standardBrowser) {
  this.#isReady = await this.#loadInStandardBrowser();
  } else {

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,8 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
+
 const SDK_METADATA = {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,
@@ -28,6 +30,10 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
  navigate={to => navigate(to)}
  initialState={__clerk_ssr_state || {}}
  sdkMetadata={SDK_METADATA}
+ telemetry={{
+ disabled: TELEMETRY_DISABLED,
+ debug: TELEMETRY_DEBUG,
+ }}
  {...restProps}
  >
  {__clerk_ssr_interstitial_html ? (

packages/gatsby-plugin-clerk/src/constants.ts

@@ -1,4 +1,5 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { isTruthy } from '@clerk/shared/underscore';
 
 export const PUBLISHABLE_KEY = process.env.GATSBY_CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
@@ -7,3 +8,6 @@ export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
 
 export const CLERK_JS = process.env.GATSBY_CLERK_JS;
 export const PROXY_URL = process.env.GATSBY_CLERK_PROXY_URL;
+
+export const TELEMETRY_DISABLED = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DISABLED);
+export const TELEMETRY_DEBUG = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DEBUG);

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,6 +15,10 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
  signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
  afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
  afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+ telemetry: {
+ disabled: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED),
+ debug: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DEBUG),
+ },
  sdkMetadata: {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,

packages/react/src/isomorphicClerk.ts

@@ -132,6 +132,11 @@ export default class IsomorphicClerk {
  this.options = options;
  this.Clerk = Clerk;
  this.mode = inBrowser() ? 'browser' : 'server';
+
+ if (!this.options.sdkMetadata) {
+ this.options.sdkMetadata = SDK_METADATA;
+ }
+
  void this.loadClerkJS();
  }
 
@@ -168,7 +173,6 @@ export default class IsomorphicClerk {
  domain: this.domain,
  } as any);
 
- c.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
  await c.load(this.options);
  } else {
  // Otherwise use the instantiated Clerk object
@@ -195,13 +199,9 @@ export default class IsomorphicClerk {
  throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
-
  await global.Clerk.load(this.options);
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
-
  if (global.Clerk?.loaded || global.Clerk?.isReady()) {
  return this.hydrateClerkJS(global.Clerk);
  }

packages/remix/src/client/RemixClerkProvider.tsx

@@ -56,6 +56,8 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  __afterSignUpUrl,
  __clerkJSUrl,
  __clerkJSVersion,
+ __telemetryDisabled,
+ __telemetryDebug,
  } = clerkState?.__internal_clerk_state || {};
 
  React.useEffect(() => {
@@ -77,6 +79,10 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  afterSignUpUrl: __afterSignUpUrl,
  clerkJSUrl: __clerkJSUrl,
  clerkJSVersion: __clerkJSVersion,
+ telemetry: {
+ disabled: __telemetryDisabled,
+ debug: __telemetryDebug,
+ },
  };
 
  return (

packages/remix/src/client/types.ts

@@ -18,6 +18,8 @@ export type ClerkState = {
  __clerk_debug: any;
  __clerkJSUrl: string | undefined;
  __clerkJSVersion: string | undefined;
+ __telemetryDisabled: boolean | undefined;
+ __telemetryDebug: boolean | undefined;
  };
 };
 

packages/remix/src/ssr/utils.ts

@@ -1,5 +1,6 @@
 import type { AuthObject, RequestState } from '@clerk/backend';
 import { constants, debugRequestState, loadInterstitialFromLocal } from '@clerk/backend';
+import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext, defer } from '@remix-run/server-runtime';
 import { json } from '@remix-run/server-runtime';
 import cookie from 'cookie';
@@ -165,6 +166,8 @@ export function getResponseClerkState(requestState: RequestState, context: AppLo
  __clerk_debug: debugRequestState(requestState),
  __clerkJSUrl: getEnvVariable('CLERK_JS', context),
  __clerkJSVersion: getEnvVariable('CLERK_JS_VERSION', context),
+ __telemetryDisabled: isTruthy(getEnvVariable('CLERK_TELEMETRY_DISABLED', context)),
+ __telemetryDebug: isTruthy(getEnvVariable('CLERK_TELEMETRY_DEBUG', context)),
  });
 
  const headers = observabilityHeadersFromRequestState(requestState);

packages/shared/.gitignore

@@ -1,2 +1,2 @@
-*/
+/*/
 !src/

packages/shared/jest.config.js

@@ -4,6 +4,9 @@ const { name } = require('./package.json');
 const config = {
  displayName: name.replace('@clerk', ''),
  injectGlobals: true,
+ globals: {
+ fetch: global.fetch,
+ },
 
  testEnvironment: 'jsdom',
  roots: ['<rootDir>/src'],

packages/shared/src/__tests__/telemetry.test.ts

@@ -0,0 +1,149 @@
+import { TelemetryCollector } from '../telemetry';
+
+jest.useFakeTimers();
+
+const TEST_PK = 'pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk';
+
+describe('TelemetryCollector', () => {
+ test('does nothing when disabled', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ disabled: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('does nothing when CLERK_TELEMETRY_DISABLED is set', async () => {
+ process.env.CLERK_TELEMETRY_DISABLED = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DISABLED = undefined;
+ });
+
+ test('does not send events when debug is enabled, logs them instead', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ debug: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+ });
+
+ test('enables debug via environment variable', async () => {
+ process.env.CLERK_TELEMETRY_DEBUG = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DEBUG = undefined;
+ });
+
+ test('sends events after a delay when buffer is not full', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('sends events immediately when the buffer limit is reached', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ maxBufferSize: 2,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+ collector.record('TEST_EVENT', {});
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+});

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

@@ -173,7 +173,7 @@ export default class Clerk implements ClerkInterface {
  #devBrowserHandler: DevBrowserHandler | null = null;
  #environment?: EnvironmentResource | null;
  #fapiClient: FapiClient;
- #telemetry: TelemetryCollector;
+ #telemetry?: TelemetryCollector;
  #instanceType: InstanceType;
  #isReady = false;
 
@@ -308,12 +308,6 @@ export default class Clerk implements ClerkInterface {
  this.#instanceType = instanceType;
  }
  this.#fapiClient = createFapiClient(this);
- this.#telemetry = new TelemetryCollector({
- clerkVersion: Clerk.version,
- verbose: true,
- samplingRate: 1,
- publishableKey: key,
- });
  BaseResource.clerk = this;
  }
 
@@ -331,6 +325,19 @@ export default class Clerk implements ClerkInterface {
  ...options,
  };
 
+ if (this.#options.sdkMetadata) {
+ Clerk.sdkMetadata = this.#options.sdkMetadata;
+ }
+
+ this.#telemetry = new TelemetryCollector({
+ clerkVersion: Clerk.version,
+ verbose: true,
+ samplingRate: 1,
+ // @ts-expect-error -- in v5 this will always be defined
+ publishableKey: this.publishableKey,
+ ...this.#options.telemetry,
+ });
+
  if (this.#options.standardBrowser) {
  this.#isReady = await this.#loadInStandardBrowser();
  } else {

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,8 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
+
 const SDK_METADATA = {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,
@@ -28,6 +30,10 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
  navigate={to => navigate(to)}
  initialState={__clerk_ssr_state || {}}
  sdkMetadata={SDK_METADATA}
+ telemetry={{
+ disabled: TELEMETRY_DISABLED,
+ debug: TELEMETRY_DEBUG,
+ }}
  {...restProps}
  >
  {__clerk_ssr_interstitial_html ? (

packages/gatsby-plugin-clerk/src/constants.ts

@@ -1,4 +1,5 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { isTruthy } from '@clerk/shared/underscore';
 
 export const PUBLISHABLE_KEY = process.env.GATSBY_CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
@@ -7,3 +8,6 @@ export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
 
 export const CLERK_JS = process.env.GATSBY_CLERK_JS;
 export const PROXY_URL = process.env.GATSBY_CLERK_PROXY_URL;
+
+export const TELEMETRY_DISABLED = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DISABLED);
+export const TELEMETRY_DEBUG = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DEBUG);

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,6 +15,10 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
  signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
  afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
  afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+ telemetry: {
+ disabled: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED),
+ debug: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DEBUG),
+ },
  sdkMetadata: {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,

packages/react/src/isomorphicClerk.ts

@@ -132,6 +132,11 @@ export default class IsomorphicClerk {
  this.options = options;
  this.Clerk = Clerk;
  this.mode = inBrowser() ? 'browser' : 'server';
+
+ if (!this.options.sdkMetadata) {
+ this.options.sdkMetadata = SDK_METADATA;
+ }
+
  void this.loadClerkJS();
  }
 
@@ -168,7 +173,6 @@ export default class IsomorphicClerk {
  domain: this.domain,
  } as any);
 
- c.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
  await c.load(this.options);
  } else {
  // Otherwise use the instantiated Clerk object
@@ -195,13 +199,9 @@ export default class IsomorphicClerk {
  throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
-
  await global.Clerk.load(this.options);
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
-
  if (global.Clerk?.loaded || global.Clerk?.isReady()) {
  return this.hydrateClerkJS(global.Clerk);
  }

packages/remix/src/client/RemixClerkProvider.tsx

@@ -56,6 +56,8 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  __afterSignUpUrl,
  __clerkJSUrl,
  __clerkJSVersion,
+ __telemetryDisabled,
+ __telemetryDebug,
  } = clerkState?.__internal_clerk_state || {};
 
  React.useEffect(() => {
@@ -77,6 +79,10 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  afterSignUpUrl: __afterSignUpUrl,
  clerkJSUrl: __clerkJSUrl,
  clerkJSVersion: __clerkJSVersion,
+ telemetry: {
+ disabled: __telemetryDisabled,
+ debug: __telemetryDebug,
+ },
  };
 
  return (

packages/remix/src/client/types.ts

@@ -18,6 +18,8 @@ export type ClerkState = {
  __clerk_debug: any;
  __clerkJSUrl: string | undefined;
  __clerkJSVersion: string | undefined;
+ __telemetryDisabled: boolean | undefined;
+ __telemetryDebug: boolean | undefined;
  };
 };
 

packages/remix/src/ssr/utils.ts

@@ -1,5 +1,6 @@
 import type { AuthObject, RequestState } from '@clerk/backend';
 import { constants, debugRequestState, loadInterstitialFromLocal } from '@clerk/backend';
+import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext, defer } from '@remix-run/server-runtime';
 import { json } from '@remix-run/server-runtime';
 import cookie from 'cookie';
@@ -165,6 +166,8 @@ export function getResponseClerkState(requestState: RequestState, context: AppLo
  __clerk_debug: debugRequestState(requestState),
  __clerkJSUrl: getEnvVariable('CLERK_JS', context),
  __clerkJSVersion: getEnvVariable('CLERK_JS_VERSION', context),
+ __telemetryDisabled: isTruthy(getEnvVariable('CLERK_TELEMETRY_DISABLED', context)),
+ __telemetryDebug: isTruthy(getEnvVariable('CLERK_TELEMETRY_DEBUG', context)),
  });
 
  const headers = observabilityHeadersFromRequestState(requestState);

packages/shared/.gitignore

@@ -1,2 +1,2 @@
-*/
+/*/
 !src/

packages/shared/jest.config.js

@@ -4,6 +4,9 @@ const { name } = require('./package.json');
 const config = {
  displayName: name.replace('@clerk', ''),
  injectGlobals: true,
+ globals: {
+ fetch: global.fetch,
+ },
 
  testEnvironment: 'jsdom',
  roots: ['<rootDir>/src'],

packages/shared/src/__tests__/telemetry.test.ts

@@ -0,0 +1,149 @@
+import { TelemetryCollector } from '../telemetry';
+
+jest.useFakeTimers();
+
+const TEST_PK = 'pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk';
+
+describe('TelemetryCollector', () => {
+ test('does nothing when disabled', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ disabled: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('does nothing when CLERK_TELEMETRY_DISABLED is set', async () => {
+ process.env.CLERK_TELEMETRY_DISABLED = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DISABLED = undefined;
+ });
+
+ test('does not send events when debug is enabled, logs them instead', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ debug: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+ });
+
+ test('enables debug via environment variable', async () => {
+ process.env.CLERK_TELEMETRY_DEBUG = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DEBUG = undefined;
+ });
+
+ test('sends events after a delay when buffer is not full', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('sends events immediately when the buffer limit is reached', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ maxBufferSize: 2,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+ collector.record('TEST_EVENT', {});
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+});

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

@@ -173,7 +173,7 @@ export default class Clerk implements ClerkInterface {
  #devBrowserHandler: DevBrowserHandler | null = null;
  #environment?: EnvironmentResource | null;
  #fapiClient: FapiClient;
- #telemetry: TelemetryCollector;
+ #telemetry?: TelemetryCollector;
  #instanceType: InstanceType;
  #isReady = false;
 
@@ -308,12 +308,6 @@ export default class Clerk implements ClerkInterface {
  this.#instanceType = instanceType;
  }
  this.#fapiClient = createFapiClient(this);
- this.#telemetry = new TelemetryCollector({
- clerkVersion: Clerk.version,
- verbose: true,
- samplingRate: 1,
- publishableKey: key,
- });
  BaseResource.clerk = this;
  }
 
@@ -331,6 +325,19 @@ export default class Clerk implements ClerkInterface {
  ...options,
  };
 
+ if (this.#options.sdkMetadata) {
+ Clerk.sdkMetadata = this.#options.sdkMetadata;
+ }
+
+ this.#telemetry = new TelemetryCollector({
+ clerkVersion: Clerk.version,
+ verbose: true,
+ samplingRate: 1,
+ // @ts-expect-error -- in v5 this will always be defined
+ publishableKey: this.publishableKey,
+ ...this.#options.telemetry,
+ });
+
  if (this.#options.standardBrowser) {
  this.#isReady = await this.#loadInStandardBrowser();
  } else {

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,8 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
+
 const SDK_METADATA = {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,
@@ -28,6 +30,10 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
  navigate={to => navigate(to)}
  initialState={__clerk_ssr_state || {}}
  sdkMetadata={SDK_METADATA}
+ telemetry={{
+ disabled: TELEMETRY_DISABLED,
+ debug: TELEMETRY_DEBUG,
+ }}
  {...restProps}
  >
  {__clerk_ssr_interstitial_html ? (

packages/gatsby-plugin-clerk/src/constants.ts

@@ -1,4 +1,5 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { isTruthy } from '@clerk/shared/underscore';
 
 export const PUBLISHABLE_KEY = process.env.GATSBY_CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
@@ -7,3 +8,6 @@ export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
 
 export const CLERK_JS = process.env.GATSBY_CLERK_JS;
 export const PROXY_URL = process.env.GATSBY_CLERK_PROXY_URL;
+
+export const TELEMETRY_DISABLED = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DISABLED);
+export const TELEMETRY_DEBUG = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DEBUG);

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,6 +15,10 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
  signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
  afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
  afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+ telemetry: {
+ disabled: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED),
+ debug: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DEBUG),
+ },
  sdkMetadata: {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,

packages/react/src/isomorphicClerk.ts

@@ -132,6 +132,11 @@ export default class IsomorphicClerk {
  this.options = options;
  this.Clerk = Clerk;
  this.mode = inBrowser() ? 'browser' : 'server';
+
+ if (!this.options.sdkMetadata) {
+ this.options.sdkMetadata = SDK_METADATA;
+ }
+
  void this.loadClerkJS();
  }
 
@@ -168,7 +173,6 @@ export default class IsomorphicClerk {
  domain: this.domain,
  } as any);
 
- c.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
  await c.load(this.options);
  } else {
  // Otherwise use the instantiated Clerk object
@@ -195,13 +199,9 @@ export default class IsomorphicClerk {
  throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
-
  await global.Clerk.load(this.options);
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
-
  if (global.Clerk?.loaded || global.Clerk?.isReady()) {
  return this.hydrateClerkJS(global.Clerk);
  }

packages/remix/src/client/RemixClerkProvider.tsx

@@ -56,6 +56,8 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  __afterSignUpUrl,
  __clerkJSUrl,
  __clerkJSVersion,
+ __telemetryDisabled,
+ __telemetryDebug,
  } = clerkState?.__internal_clerk_state || {};
 
  React.useEffect(() => {
@@ -77,6 +79,10 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  afterSignUpUrl: __afterSignUpUrl,
  clerkJSUrl: __clerkJSUrl,
  clerkJSVersion: __clerkJSVersion,
+ telemetry: {
+ disabled: __telemetryDisabled,
+ debug: __telemetryDebug,
+ },
  };
 
  return (

packages/remix/src/client/types.ts

@@ -18,6 +18,8 @@ export type ClerkState = {
  __clerk_debug: any;
  __clerkJSUrl: string | undefined;
  __clerkJSVersion: string | undefined;
+ __telemetryDisabled: boolean | undefined;
+ __telemetryDebug: boolean | undefined;
  };
 };
 

packages/remix/src/ssr/utils.ts

@@ -1,5 +1,6 @@
 import type { AuthObject, RequestState } from '@clerk/backend';
 import { constants, debugRequestState, loadInterstitialFromLocal } from '@clerk/backend';
+import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext, defer } from '@remix-run/server-runtime';
 import { json } from '@remix-run/server-runtime';
 import cookie from 'cookie';
@@ -165,6 +166,8 @@ export function getResponseClerkState(requestState: RequestState, context: AppLo
  __clerk_debug: debugRequestState(requestState),
  __clerkJSUrl: getEnvVariable('CLERK_JS', context),
  __clerkJSVersion: getEnvVariable('CLERK_JS_VERSION', context),
+ __telemetryDisabled: isTruthy(getEnvVariable('CLERK_TELEMETRY_DISABLED', context)),
+ __telemetryDebug: isTruthy(getEnvVariable('CLERK_TELEMETRY_DEBUG', context)),
  });
 
  const headers = observabilityHeadersFromRequestState(requestState);

packages/shared/.gitignore

@@ -1,2 +1,2 @@
-*/
+/*/
 !src/

packages/shared/jest.config.js

@@ -4,6 +4,9 @@ const { name } = require('./package.json');
 const config = {
  displayName: name.replace('@clerk', ''),
  injectGlobals: true,
+ globals: {
+ fetch: global.fetch,
+ },
 
  testEnvironment: 'jsdom',
  roots: ['<rootDir>/src'],

packages/shared/src/__tests__/telemetry.test.ts

@@ -0,0 +1,149 @@
+import { TelemetryCollector } from '../telemetry';
+
+jest.useFakeTimers();
+
+const TEST_PK = 'pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk';
+
+describe('TelemetryCollector', () => {
+ test('does nothing when disabled', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ disabled: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('does nothing when CLERK_TELEMETRY_DISABLED is set', async () => {
+ process.env.CLERK_TELEMETRY_DISABLED = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DISABLED = undefined;
+ });
+
+ test('does not send events when debug is enabled, logs them instead', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ debug: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+ });
+
+ test('enables debug via environment variable', async () => {
+ process.env.CLERK_TELEMETRY_DEBUG = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DEBUG = undefined;
+ });
+
+ test('sends events after a delay when buffer is not full', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('sends events immediately when the buffer limit is reached', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ maxBufferSize: 2,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+ collector.record('TEST_EVENT', {});
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+});

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

@@ -173,7 +173,7 @@ export default class Clerk implements ClerkInterface {
  #devBrowserHandler: DevBrowserHandler | null = null;
  #environment?: EnvironmentResource | null;
  #fapiClient: FapiClient;
- #telemetry: TelemetryCollector;
+ #telemetry?: TelemetryCollector;
  #instanceType: InstanceType;
  #isReady = false;
 
@@ -308,12 +308,6 @@ export default class Clerk implements ClerkInterface {
  this.#instanceType = instanceType;
  }
  this.#fapiClient = createFapiClient(this);
- this.#telemetry = new TelemetryCollector({
- clerkVersion: Clerk.version,
- verbose: true,
- samplingRate: 1,
- publishableKey: key,
- });
  BaseResource.clerk = this;
  }
 
@@ -331,6 +325,19 @@ export default class Clerk implements ClerkInterface {
  ...options,
  };
 
+ if (this.#options.sdkMetadata) {
+ Clerk.sdkMetadata = this.#options.sdkMetadata;
+ }
+
+ this.#telemetry = new TelemetryCollector({
+ clerkVersion: Clerk.version,
+ verbose: true,
+ samplingRate: 1,
+ // @ts-expect-error -- in v5 this will always be defined
+ publishableKey: this.publishableKey,
+ ...this.#options.telemetry,
+ });
+
  if (this.#options.standardBrowser) {
  this.#isReady = await this.#loadInStandardBrowser();
  } else {

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,8 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
+
 const SDK_METADATA = {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,
@@ -28,6 +30,10 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
  navigate={to => navigate(to)}
  initialState={__clerk_ssr_state || {}}
  sdkMetadata={SDK_METADATA}
+ telemetry={{
+ disabled: TELEMETRY_DISABLED,
+ debug: TELEMETRY_DEBUG,
+ }}
  {...restProps}
  >
  {__clerk_ssr_interstitial_html ? (

packages/gatsby-plugin-clerk/src/constants.ts

@@ -1,4 +1,5 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { isTruthy } from '@clerk/shared/underscore';
 
 export const PUBLISHABLE_KEY = process.env.GATSBY_CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
@@ -7,3 +8,6 @@ export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
 
 export const CLERK_JS = process.env.GATSBY_CLERK_JS;
 export const PROXY_URL = process.env.GATSBY_CLERK_PROXY_URL;
+
+export const TELEMETRY_DISABLED = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DISABLED);
+export const TELEMETRY_DEBUG = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DEBUG);

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,6 +15,10 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
  signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
  afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
  afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+ telemetry: {
+ disabled: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED),
+ debug: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DEBUG),
+ },
  sdkMetadata: {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,

packages/react/src/isomorphicClerk.ts

@@ -132,6 +132,11 @@ export default class IsomorphicClerk {
  this.options = options;
  this.Clerk = Clerk;
  this.mode = inBrowser() ? 'browser' : 'server';
+
+ if (!this.options.sdkMetadata) {
+ this.options.sdkMetadata = SDK_METADATA;
+ }
+
  void this.loadClerkJS();
  }
 
@@ -168,7 +173,6 @@ export default class IsomorphicClerk {
  domain: this.domain,
  } as any);
 
- c.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
  await c.load(this.options);
  } else {
  // Otherwise use the instantiated Clerk object
@@ -195,13 +199,9 @@ export default class IsomorphicClerk {
  throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
-
  await global.Clerk.load(this.options);
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
-
  if (global.Clerk?.loaded || global.Clerk?.isReady()) {
  return this.hydrateClerkJS(global.Clerk);
  }

packages/remix/src/client/RemixClerkProvider.tsx

@@ -56,6 +56,8 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  __afterSignUpUrl,
  __clerkJSUrl,
  __clerkJSVersion,
+ __telemetryDisabled,
+ __telemetryDebug,
  } = clerkState?.__internal_clerk_state || {};
 
  React.useEffect(() => {
@@ -77,6 +79,10 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  afterSignUpUrl: __afterSignUpUrl,
  clerkJSUrl: __clerkJSUrl,
  clerkJSVersion: __clerkJSVersion,
+ telemetry: {
+ disabled: __telemetryDisabled,
+ debug: __telemetryDebug,
+ },
  };
 
  return (

packages/remix/src/client/types.ts

@@ -18,6 +18,8 @@ export type ClerkState = {
  __clerk_debug: any;
  __clerkJSUrl: string | undefined;
  __clerkJSVersion: string | undefined;
+ __telemetryDisabled: boolean | undefined;
+ __telemetryDebug: boolean | undefined;
  };
 };
 

packages/remix/src/ssr/utils.ts

@@ -1,5 +1,6 @@
 import type { AuthObject, RequestState } from '@clerk/backend';
 import { constants, debugRequestState, loadInterstitialFromLocal } from '@clerk/backend';
+import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext, defer } from '@remix-run/server-runtime';
 import { json } from '@remix-run/server-runtime';
 import cookie from 'cookie';
@@ -165,6 +166,8 @@ export function getResponseClerkState(requestState: RequestState, context: AppLo
  __clerk_debug: debugRequestState(requestState),
  __clerkJSUrl: getEnvVariable('CLERK_JS', context),
  __clerkJSVersion: getEnvVariable('CLERK_JS_VERSION', context),
+ __telemetryDisabled: isTruthy(getEnvVariable('CLERK_TELEMETRY_DISABLED', context)),
+ __telemetryDebug: isTruthy(getEnvVariable('CLERK_TELEMETRY_DEBUG', context)),
  });
 
  const headers = observabilityHeadersFromRequestState(requestState);

packages/shared/.gitignore

@@ -1,2 +1,2 @@
-*/
+/*/
 !src/

packages/shared/jest.config.js

@@ -4,6 +4,9 @@ const { name } = require('./package.json');
 const config = {
  displayName: name.replace('@clerk', ''),
  injectGlobals: true,
+ globals: {
+ fetch: global.fetch,
+ },
 
  testEnvironment: 'jsdom',
  roots: ['<rootDir>/src'],

packages/shared/src/__tests__/telemetry.test.ts

@@ -0,0 +1,149 @@
+import { TelemetryCollector } from '../telemetry';
+
+jest.useFakeTimers();
+
+const TEST_PK = 'pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk';
+
+describe('TelemetryCollector', () => {
+ test('does nothing when disabled', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ disabled: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('does nothing when CLERK_TELEMETRY_DISABLED is set', async () => {
+ process.env.CLERK_TELEMETRY_DISABLED = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DISABLED = undefined;
+ });
+
+ test('does not send events when debug is enabled, logs them instead', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ debug: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+ });
+
+ test('enables debug via environment variable', async () => {
+ process.env.CLERK_TELEMETRY_DEBUG = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DEBUG = undefined;
+ });
+
+ test('sends events after a delay when buffer is not full', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('sends events immediately when the buffer limit is reached', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ maxBufferSize: 2,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+ collector.record('TEST_EVENT', {});
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+});

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

@@ -173,7 +173,7 @@ export default class Clerk implements ClerkInterface {
  #devBrowserHandler: DevBrowserHandler | null = null;
  #environment?: EnvironmentResource | null;
  #fapiClient: FapiClient;
- #telemetry: TelemetryCollector;
+ #telemetry?: TelemetryCollector;
  #instanceType: InstanceType;
  #isReady = false;
 
@@ -308,12 +308,6 @@ export default class Clerk implements ClerkInterface {
  this.#instanceType = instanceType;
  }
  this.#fapiClient = createFapiClient(this);
- this.#telemetry = new TelemetryCollector({
- clerkVersion: Clerk.version,
- verbose: true,
- samplingRate: 1,
- publishableKey: key,
- });
  BaseResource.clerk = this;
  }
 
@@ -331,6 +325,19 @@ export default class Clerk implements ClerkInterface {
  ...options,
  };
 
+ if (this.#options.sdkMetadata) {
+ Clerk.sdkMetadata = this.#options.sdkMetadata;
+ }
+
+ this.#telemetry = new TelemetryCollector({
+ clerkVersion: Clerk.version,
+ verbose: true,
+ samplingRate: 1,
+ // @ts-expect-error -- in v5 this will always be defined
+ publishableKey: this.publishableKey,
+ ...this.#options.telemetry,
+ });
+
  if (this.#options.standardBrowser) {
  this.#isReady = await this.#loadInStandardBrowser();
  } else {

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,8 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
+
 const SDK_METADATA = {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,
@@ -28,6 +30,10 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
  navigate={to => navigate(to)}
  initialState={__clerk_ssr_state || {}}
  sdkMetadata={SDK_METADATA}
+ telemetry={{
+ disabled: TELEMETRY_DISABLED,
+ debug: TELEMETRY_DEBUG,
+ }}
  {...restProps}
  >
  {__clerk_ssr_interstitial_html ? (

packages/gatsby-plugin-clerk/src/constants.ts

@@ -1,4 +1,5 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { isTruthy } from '@clerk/shared/underscore';
 
 export const PUBLISHABLE_KEY = process.env.GATSBY_CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
@@ -7,3 +8,6 @@ export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
 
 export const CLERK_JS = process.env.GATSBY_CLERK_JS;
 export const PROXY_URL = process.env.GATSBY_CLERK_PROXY_URL;
+
+export const TELEMETRY_DISABLED = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DISABLED);
+export const TELEMETRY_DEBUG = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DEBUG);

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,6 +15,10 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
  signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
  afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
  afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+ telemetry: {
+ disabled: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED),
+ debug: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DEBUG),
+ },
  sdkMetadata: {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,

packages/react/src/isomorphicClerk.ts

@@ -132,6 +132,11 @@ export default class IsomorphicClerk {
  this.options = options;
  this.Clerk = Clerk;
  this.mode = inBrowser() ? 'browser' : 'server';
+
+ if (!this.options.sdkMetadata) {
+ this.options.sdkMetadata = SDK_METADATA;
+ }
+
  void this.loadClerkJS();
  }
 
@@ -168,7 +173,6 @@ export default class IsomorphicClerk {
  domain: this.domain,
  } as any);
 
- c.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
  await c.load(this.options);
  } else {
  // Otherwise use the instantiated Clerk object
@@ -195,13 +199,9 @@ export default class IsomorphicClerk {
  throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
-
  await global.Clerk.load(this.options);
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
-
  if (global.Clerk?.loaded || global.Clerk?.isReady()) {
  return this.hydrateClerkJS(global.Clerk);
  }

packages/remix/src/client/RemixClerkProvider.tsx

@@ -56,6 +56,8 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  __afterSignUpUrl,
  __clerkJSUrl,
  __clerkJSVersion,
+ __telemetryDisabled,
+ __telemetryDebug,
  } = clerkState?.__internal_clerk_state || {};
 
  React.useEffect(() => {
@@ -77,6 +79,10 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  afterSignUpUrl: __afterSignUpUrl,
  clerkJSUrl: __clerkJSUrl,
  clerkJSVersion: __clerkJSVersion,
+ telemetry: {
+ disabled: __telemetryDisabled,
+ debug: __telemetryDebug,
+ },
  };
 
  return (

packages/remix/src/client/types.ts

@@ -18,6 +18,8 @@ export type ClerkState = {
  __clerk_debug: any;
  __clerkJSUrl: string | undefined;
  __clerkJSVersion: string | undefined;
+ __telemetryDisabled: boolean | undefined;
+ __telemetryDebug: boolean | undefined;
  };
 };
 

packages/remix/src/ssr/utils.ts

@@ -1,5 +1,6 @@
 import type { AuthObject, RequestState } from '@clerk/backend';
 import { constants, debugRequestState, loadInterstitialFromLocal } from '@clerk/backend';
+import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext, defer } from '@remix-run/server-runtime';
 import { json } from '@remix-run/server-runtime';
 import cookie from 'cookie';
@@ -165,6 +166,8 @@ export function getResponseClerkState(requestState: RequestState, context: AppLo
  __clerk_debug: debugRequestState(requestState),
  __clerkJSUrl: getEnvVariable('CLERK_JS', context),
  __clerkJSVersion: getEnvVariable('CLERK_JS_VERSION', context),
+ __telemetryDisabled: isTruthy(getEnvVariable('CLERK_TELEMETRY_DISABLED', context)),
+ __telemetryDebug: isTruthy(getEnvVariable('CLERK_TELEMETRY_DEBUG', context)),
  });
 
  const headers = observabilityHeadersFromRequestState(requestState);

packages/shared/.gitignore

@@ -1,2 +1,2 @@
-*/
+/*/
 !src/

packages/shared/jest.config.js

@@ -4,6 +4,9 @@ const { name } = require('./package.json');
 const config = {
  displayName: name.replace('@clerk', ''),
  injectGlobals: true,
+ globals: {
+ fetch: global.fetch,
+ },
 
  testEnvironment: 'jsdom',
  roots: ['<rootDir>/src'],

packages/shared/src/__tests__/telemetry.test.ts

@@ -0,0 +1,149 @@
+import { TelemetryCollector } from '../telemetry';
+
+jest.useFakeTimers();
+
+const TEST_PK = 'pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk';
+
+describe('TelemetryCollector', () => {
+ test('does nothing when disabled', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ disabled: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('does nothing when CLERK_TELEMETRY_DISABLED is set', async () => {
+ process.env.CLERK_TELEMETRY_DISABLED = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DISABLED = undefined;
+ });
+
+ test('does not send events when debug is enabled, logs them instead', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ debug: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+ });
+
+ test('enables debug via environment variable', async () => {
+ process.env.CLERK_TELEMETRY_DEBUG = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DEBUG = undefined;
+ });
+
+ test('sends events after a delay when buffer is not full', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('sends events immediately when the buffer limit is reached', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ maxBufferSize: 2,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+ collector.record('TEST_EVENT', {});
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+});

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

@@ -173,7 +173,7 @@ export default class Clerk implements ClerkInterface {
  #devBrowserHandler: DevBrowserHandler | null = null;
  #environment?: EnvironmentResource | null;
  #fapiClient: FapiClient;
- #telemetry: TelemetryCollector;
+ #telemetry?: TelemetryCollector;
  #instanceType: InstanceType;
  #isReady = false;
 
@@ -308,12 +308,6 @@ export default class Clerk implements ClerkInterface {
  this.#instanceType = instanceType;
  }
  this.#fapiClient = createFapiClient(this);
- this.#telemetry = new TelemetryCollector({
- clerkVersion: Clerk.version,
- verbose: true,
- samplingRate: 1,
- publishableKey: key,
- });
  BaseResource.clerk = this;
  }
 
@@ -331,6 +325,19 @@ export default class Clerk implements ClerkInterface {
  ...options,
  };
 
+ if (this.#options.sdkMetadata) {
+ Clerk.sdkMetadata = this.#options.sdkMetadata;
+ }
+
+ this.#telemetry = new TelemetryCollector({
+ clerkVersion: Clerk.version,
+ verbose: true,
+ samplingRate: 1,
+ // @ts-expect-error -- in v5 this will always be defined
+ publishableKey: this.publishableKey,
+ ...this.#options.telemetry,
+ });
+
  if (this.#options.standardBrowser) {
  this.#isReady = await this.#loadInStandardBrowser();
  } else {

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,8 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
+
 const SDK_METADATA = {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,
@@ -28,6 +30,10 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
  navigate={to => navigate(to)}
  initialState={__clerk_ssr_state || {}}
  sdkMetadata={SDK_METADATA}
+ telemetry={{
+ disabled: TELEMETRY_DISABLED,
+ debug: TELEMETRY_DEBUG,
+ }}
  {...restProps}
  >
  {__clerk_ssr_interstitial_html ? (

packages/gatsby-plugin-clerk/src/constants.ts

@@ -1,4 +1,5 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { isTruthy } from '@clerk/shared/underscore';
 
 export const PUBLISHABLE_KEY = process.env.GATSBY_CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
@@ -7,3 +8,6 @@ export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
 
 export const CLERK_JS = process.env.GATSBY_CLERK_JS;
 export const PROXY_URL = process.env.GATSBY_CLERK_PROXY_URL;
+
+export const TELEMETRY_DISABLED = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DISABLED);
+export const TELEMETRY_DEBUG = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DEBUG);

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,6 +15,10 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
  signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
  afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
  afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+ telemetry: {
+ disabled: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED),
+ debug: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DEBUG),
+ },
  sdkMetadata: {
  name: PACKAGE_NAME,
  version: PACKAGE_VERSION,

packages/react/src/isomorphicClerk.ts

@@ -132,6 +132,11 @@ export default class IsomorphicClerk {
  this.options = options;
  this.Clerk = Clerk;
  this.mode = inBrowser() ? 'browser' : 'server';
+
+ if (!this.options.sdkMetadata) {
+ this.options.sdkMetadata = SDK_METADATA;
+ }
+
  void this.loadClerkJS();
  }
 
@@ -168,7 +173,6 @@ export default class IsomorphicClerk {
  domain: this.domain,
  } as any);
 
- c.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
  await c.load(this.options);
  } else {
  // Otherwise use the instantiated Clerk object
@@ -195,13 +199,9 @@ export default class IsomorphicClerk {
  throw new Error('Failed to download latest ClerkJS. Contact support@clerk.com.');
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
-
  await global.Clerk.load(this.options);
  }
 
- global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
-
  if (global.Clerk?.loaded || global.Clerk?.isReady()) {
  return this.hydrateClerkJS(global.Clerk);
  }

packages/remix/src/client/RemixClerkProvider.tsx

@@ -56,6 +56,8 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  __afterSignUpUrl,
  __clerkJSUrl,
  __clerkJSVersion,
+ __telemetryDisabled,
+ __telemetryDebug,
  } = clerkState?.__internal_clerk_state || {};
 
  React.useEffect(() => {
@@ -77,6 +79,10 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
  afterSignUpUrl: __afterSignUpUrl,
  clerkJSUrl: __clerkJSUrl,
  clerkJSVersion: __clerkJSVersion,
+ telemetry: {
+ disabled: __telemetryDisabled,
+ debug: __telemetryDebug,
+ },
  };
 
  return (

packages/remix/src/client/types.ts

@@ -18,6 +18,8 @@ export type ClerkState = {
  __clerk_debug: any;
  __clerkJSUrl: string | undefined;
  __clerkJSVersion: string | undefined;
+ __telemetryDisabled: boolean | undefined;
+ __telemetryDebug: boolean | undefined;
  };
 };
 

packages/remix/src/ssr/utils.ts

@@ -1,5 +1,6 @@
 import type { AuthObject, RequestState } from '@clerk/backend';
 import { constants, debugRequestState, loadInterstitialFromLocal } from '@clerk/backend';
+import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext, defer } from '@remix-run/server-runtime';
 import { json } from '@remix-run/server-runtime';
 import cookie from 'cookie';
@@ -165,6 +166,8 @@ export function getResponseClerkState(requestState: RequestState, context: AppLo
  __clerk_debug: debugRequestState(requestState),
  __clerkJSUrl: getEnvVariable('CLERK_JS', context),
  __clerkJSVersion: getEnvVariable('CLERK_JS_VERSION', context),
+ __telemetryDisabled: isTruthy(getEnvVariable('CLERK_TELEMETRY_DISABLED', context)),
+ __telemetryDebug: isTruthy(getEnvVariable('CLERK_TELEMETRY_DEBUG', context)),
  });
 
  const headers = observabilityHeadersFromRequestState(requestState);

packages/shared/.gitignore

@@ -1,2 +1,2 @@
-*/
+/*/
 !src/

packages/shared/jest.config.js

@@ -4,6 +4,9 @@ const { name } = require('./package.json');
 const config = {
  displayName: name.replace('@clerk', ''),
  injectGlobals: true,
+ globals: {
+ fetch: global.fetch,
+ },
 
  testEnvironment: 'jsdom',
  roots: ['<rootDir>/src'],

packages/shared/src/__tests__/telemetry.test.ts

@@ -0,0 +1,149 @@
+import { TelemetryCollector } from '../telemetry';
+
+jest.useFakeTimers();
+
+const TEST_PK = 'pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk';
+
+describe('TelemetryCollector', () => {
+ test('does nothing when disabled', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ disabled: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('does nothing when CLERK_TELEMETRY_DISABLED is set', async () => {
+ process.env.CLERK_TELEMETRY_DISABLED = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DISABLED = undefined;
+ });
+
+ test('does not send events when debug is enabled, logs them instead', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ debug: true,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+ });
+
+ test('enables debug via environment variable', async () => {
+ process.env.CLERK_TELEMETRY_DEBUG = '1';
+
+ const fetchSpy = jest.spyOn(global, 'fetch');
+ const consoleSpy = jest.spyOn(global.console, 'log');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).not.toHaveBeenCalled();
+
+ expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+ [
+ [
+ {
+ "cv": "",
+ "event": "TEST_EVENT",
+ "it": "development",
+ "payload": {},
+ "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+ "sdk": undefined,
+ "sdkv": undefined,
+ },
+ ],
+ ]
+ `);
+
+ consoleSpy.mockRestore();
+ fetchSpy.mockRestore();
+
+ process.env.CLERK_TELEMETRY_DEBUG = undefined;
+ });
+
+ test('sends events after a delay when buffer is not full', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+
+ jest.runAllTimers();
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+
+ test('sends events immediately when the buffer limit is reached', async () => {
+ const fetchSpy = jest.spyOn(global, 'fetch');
+
+ const collector = new TelemetryCollector({
+ maxBufferSize: 2,
+ publishableKey: TEST_PK,
+ });
+
+ collector.record('TEST_EVENT', {});
+ collector.record('TEST_EVENT', {});
+
+ expect(fetchSpy).toHaveBeenCalled();
+
+ fetchSpy.mockRestore();
+ });
+});