refactor(types,shared,elements): Assign telemetry property to main Clerk interface (#3329)

* refactor(types,shared): Create separate type interface for `TelemetryCollector`

* fix(shared): Remove `TelemetryEvent` interfaces

* fix(elements): Remove assertion for `telemetry`

* docs(types): Add JSDocs on telemetry types to indicate internal usage

* refactor(elements): Remove `useTelemetry` hook

* Update .changeset/heavy-kings-fix.md

---------

Co-authored-by: Lennart <lekoarts@gmail.com>

Author: LauraBeatris

.changeset/heavy-kings-fix.md

@@ -0,0 +1,9 @@
+---
+'@clerk/shared': patch
+'@clerk/types': patch
+'@clerk/elements': patch
+---
+
+The following are all internal changes and not relevant to any end-user:
+
+Create type interface for `TelemetryCollector` on `@clerk/types`. This allows to assign `telemetry` on the main Clerk SDK object, while inheriting from the actual `TelemetryCollector` implementation.

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

@@ -151,7 +151,7 @@ export class Clerk implements ClerkInterface {
   public organization: OrganizationResource | null | undefined;
   public user: UserResource | null | undefined;
   public __internal_country?: string | null;
-  public telemetry?: TelemetryCollector;
+  public telemetry: TelemetryCollector | undefined;
 
   protected internal_last_error: ClerkAPIError | null = null;
 

packages/elements/src/react/common/form/index.tsx

@@ -1,3 +1,4 @@
+import { useClerk } from '@clerk/clerk-react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { Autocomplete } from '@clerk/types';
 import { composeEventHandlers } from '@radix-ui/primitive';
@@ -35,7 +36,6 @@ import {
 } from '~/internals/machines/form/form.context';
 import { usePassword } from '~/react/hooks/use-password.hook';
 import type { ErrorMessagesKey } from '~/react/utils/generate-password-error-text';
-import { useTelemetry } from '~/react/utils/telemetry';
 
 import type { OTPInputProps } from './otp';
 import { OTP_LENGTH_DEFAULT, OTPInput } from './otp';
@@ -530,9 +530,9 @@ type FormInputProps =
  */
 const Input = React.forwardRef<React.ElementRef<typeof RadixControl>, FormInputProps>(
   (props: FormInputProps, forwardedRef) => {
-    const telemetry = useTelemetry();
+    const clerk = useClerk();
 
-    telemetry?.record(
+    clerk.telemetry?.record(
       eventComponentMounted('Elements_Input', {
         type: props.type ?? false,
         // @ts-expect-error - Depending on type the props can be different

packages/elements/src/react/common/loading.tsx

@@ -1,3 +1,4 @@
+import { useClerk } from '@clerk/clerk-react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 import type { OAuthProvider, SamlStrategy } from '@clerk/types';
 import * as React from 'react';
@@ -18,7 +19,6 @@ import type { TSignUpStep } from '~/react/sign-up/step';
 import { SIGN_UP_STEPS } from '~/react/sign-up/step';
 import { SignUpVerificationCtx } from '~/react/sign-up/verifications';
 import { mapScopeToStrategy } from '~/react/utils/map-scope-to-strategy';
-import { useTelemetry } from '~/react/utils/telemetry';
 
 type Strategy = OAuthProvider | SamlStrategy | 'metamask';
 type LoadingScope<T extends TSignInStep | TSignUpStep> = 'global' | `step:${T}` | `provider:${Strategy}` | undefined;
@@ -82,9 +82,9 @@ function isSignUpScope(scope: LoadingScope<TSignInStep | TSignUpStep>): scope is
  * </SignIn.Step>
  */
 export function Loading({ children, scope }: LoadingProps) {
-  const telemetry = useTelemetry();
+  const clerk = useClerk();
 
-  telemetry?.record(eventComponentMounted('Elements_Loading', { scope: scope ?? false }));
+  clerk.telemetry?.record(eventComponentMounted('Elements_Loading', { scope: scope ?? false }));
 
   const signInRouterRef = SignInRouterCtx.useActorRef(true);
   const signUpRouterRef = SignUpRouterCtx.useActorRef(true);

packages/elements/src/react/sign-in/root.tsx

@@ -10,7 +10,6 @@ import { SignInRouterMachine } from '~/internals/machines/sign-in';
 import { consoleInspector } from '~/internals/utils/inspector';
 import { Router, useClerkRouter, useNextRouter } from '~/react/router';
 import { SignInRouterCtx } from '~/react/sign-in/context';
-import { useTelemetry } from '~/react/utils/telemetry';
 
 import { Form } from '../common/form';
 
@@ -83,9 +82,9 @@ export function SignInRoot({
   fallback = null,
   exampleMode,
 }: SignInRootProps): JSX.Element | null {
-  const telemetry = useTelemetry();
+  const clerk = useClerk();
 
-  telemetry?.record(
+  clerk.telemetry?.record(
     eventComponentMounted('Elements_SignInRoot', {
       path,
       fallback: Boolean(fallback),

packages/elements/src/react/sign-in/step/step.tsx

@@ -1,7 +1,7 @@
+import { useClerk } from '@clerk/clerk-react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';
-import { useTelemetry } from '~/react/utils/telemetry';
 
 import type { SignInChooseStrategyProps } from '../choose-strategy';
 import { SignInChooseStrategy, SignInForgotPassword } from '../choose-strategy';
@@ -46,9 +46,9 @@ export type SignInStepProps =
  * </SignIn.Root>
  */
 export function SignInStep(props: SignInStepProps) {
-  const telemetry = useTelemetry();
+  const clerk = useClerk();
 
-  telemetry?.record(eventComponentMounted('Elements_SignInStep', { name: props.name }));
+  clerk.telemetry?.record(eventComponentMounted('Elements_SignInStep', { name: props.name }));
 
   switch (props.name) {
     case SIGN_IN_STEPS['start']:

packages/elements/src/react/sign-up/root.tsx

@@ -11,7 +11,6 @@ import { SignUpRouterMachine } from '~/internals/machines/sign-up';
 import { consoleInspector } from '~/internals/utils/inspector';
 import { Router, useClerkRouter, useNextRouter } from '~/react/router';
 import { SignUpRouterCtx } from '~/react/sign-up/context';
-import { useTelemetry } from '~/react/utils/telemetry';
 
 import { Form } from '../common/form';
 
@@ -80,9 +79,9 @@ export function SignUpRoot({
   fallback = null,
   exampleMode,
 }: SignUpRootProps): JSX.Element | null {
-  const telemetry = useTelemetry();
+  const clerk = useClerk();
 
-  telemetry?.record(
+  clerk.telemetry?.record(
     eventComponentMounted('Elements_SignUpRoot', {
       path,
       fallback: Boolean(fallback),

packages/elements/src/react/sign-up/step.tsx

@@ -1,7 +1,7 @@
+import { useClerk } from '@clerk/clerk-react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
 
 import { ClerkElementsRuntimeError } from '~/internals/errors';
-import { useTelemetry } from '~/react/utils/telemetry';
 
 import type { SignUpContinueProps } from './continue';
 import { SignUpContinue } from './continue';
@@ -39,9 +39,9 @@ export type SignUpStepProps =
  * </SignUp.Root>
  */
 export function SignUpStep(props: SignUpStepProps) {
-  const telemetry = useTelemetry();
+  const clerk = useClerk();
 
-  telemetry?.record(eventComponentMounted('Elements_SignUpStep', { name: props.name }));
+  clerk.telemetry?.record(eventComponentMounted('Elements_SignUpStep', { name: props.name }));
 
   switch (props.name) {
     case SIGN_UP_STEPS.start:

packages/elements/src/react/utils/telemetry.ts

@@ -10,12 +10,17 @@
  *
  * For more information, please see the telemetry documentation page: https://clerk.com/docs/telemetry
  */
-import type { InstanceType } from '@clerk/types';
+import type {
+  InstanceType,
+  TelemetryCollector as TelemetryCollectorInterface,
+  TelemetryEvent,
+  TelemetryEventRaw,
+} from '@clerk/types';
 
 import { parsePublishableKey } from '../keys';
 import { isTruthy } from '../underscore';
 import { TelemetryEventThrottler } from './throttler';
-import type { TelemetryCollectorOptions, TelemetryEvent, TelemetryEventRaw } from './types';
+import type { TelemetryCollectorOptions } from './types';
 
 type TelemetryCollectorConfig = Pick<
   TelemetryCollectorOptions,
@@ -42,7 +47,7 @@ const DEFAULT_CONFIG: Partial<TelemetryCollectorConfig> = {
   endpoint: 'https://clerk-telemetry.com',
 };
 
-export class TelemetryCollector {
+export class TelemetryCollector implements TelemetryCollectorInterface {
   #config: Required<TelemetryCollectorConfig>;
   #eventThrottler: TelemetryEventThrottler;
   #metadata: TelemetryMetadata = {} as TelemetryMetadata;

packages/shared/src/telemetry/collector.ts

@@ -1,4 +1,4 @@
-import type { TelemetryEventRaw } from '../types';
+import type { TelemetryEventRaw } from '@clerk/types';
 
 const EVENT_COMPONENT_MOUNTED = 'COMPONENT_MOUNTED' as const;
 const EVENT_SAMPLING_RATE = 0.1;

packages/shared/src/telemetry/events/component-mounted.ts

@@ -1,4 +1,4 @@
-import type { TelemetryEventRaw } from '../types';
+import type { TelemetryEventRaw } from '@clerk/types';
 
 const EVENT_METHOD_CALLED = 'METHOD_CALLED' as const;
 

packages/shared/src/telemetry/events/method-called.ts

@@ -1,4 +1,4 @@
-import type { TelemetryEvent } from './types';
+import type { TelemetryEvent } from '@clerk/types';
 
 type TtlInMilliseconds = number;
 

packages/shared/src/telemetry/throttler.ts

@@ -1,5 +1,3 @@
-import type { InstanceType } from '@clerk/types';
-
 export type TelemetryCollectorOptions = {
   /**
    * If true, telemetry will not be collected.
@@ -38,38 +36,3 @@ export type TelemetryCollectorOptions = {
    */
   sdkVersion?: string;
 };
-
-export type TelemetryEvent = {
-  event: string;
-  /**
-   * publishableKey
-   */
-  pk?: string;
-  /**
-   * secretKey
-   */
-  sk?: string;
-  /**
-   * instanceType
-   */
-  it: InstanceType;
-  /**
-   * clerkVersion
-   */
-  cv: string;
-  /**
-   * SDK
-   */
-  sdk?: string;
-  /**
-   * SDK Version
-   */
-  sdkv?: string;
-  payload: Record<string, string | number | boolean>;
-};
-
-export type TelemetryEventRaw<Payload = TelemetryEvent['payload']> = {
-  event: TelemetryEvent['event'];
-  eventSamplingRate?: number;
-  payload: Payload;
-};

packages/shared/src/telemetry/types.ts

@@ -1,3 +1,5 @@
+import type { TelemetryCollector } from 'telemetry';
+
 import type {
   Appearance,
   CreateOrganizationTheme,
@@ -11,6 +13,7 @@ import type {
 } from './appearance';
 import type { ClientResource } from './client';
 import type { CustomPage } from './customPages';
+import type { InstanceType } from './instance';
 import type { DisplayThemeJSON } from './json';
 import type { LocalizationResource } from './localization';
 import type { OAuthProvider, OAuthScope } from './oauth';
@@ -30,8 +33,6 @@ import type { ActiveSessionResource } from './session';
 import type { UserResource } from './user';
 import type { Autocomplete, DeepPartial, DeepSnakeToCamel } from './utils';
 
-export type InstanceType = 'production' | 'development';
-
 export type SDKMetadata = {
   name: string;
   version: string;
@@ -114,6 +115,8 @@ export interface Clerk {
   /** Current User. */
   user: UserResource | null | undefined;
 
+  telemetry: TelemetryCollector | undefined;
+
   /**
    * Signs out the current user on single-session instances, or all users on multi-session instances
    * @param signOutCallback - Optional A callback that runs after sign out completes.

packages/types/src/clerk.ts

@@ -15,6 +15,7 @@ export * from './factors';
 export * from './identificationLink';
 export * from './identifiers';
 export * from './image';
+export * from './instance';
 export * from './json';
 export * from './jwt';
 export * from './key';
@@ -45,6 +46,7 @@ export * from './strategies';
 export * from './theme';
 export * from './token';
 export * from './totp';
+export * from './telemetry';
 export * from './user';
 export * from './userOrganizationInvitation';
 export * from './userSettings';

packages/types/src/index.ts

@@ -0,0 +1 @@
+export type InstanceType = 'production' | 'development';

packages/types/src/instance.ts

@@ -1,4 +1,4 @@
-import type { InstanceType } from './clerk';
+import type { InstanceType } from './instance';
 
 export type PublishableKey = {
   frontendApi: string;

packages/types/src/key.ts

@@ -0,0 +1,48 @@
+import type { InstanceType } from 'instance';
+
+/**
+ * @internal
+ */
+export type TelemetryEvent = {
+  event: string;
+  /**
+   * publishableKey
+   */
+  pk?: string;
+  /**
+   * secretKey
+   */
+  sk?: string;
+  /**
+   * instanceType
+   */
+  it: InstanceType;
+  /**
+   * clerkVersion
+   */
+  cv: string;
+  /**
+   * SDK
+   */
+  sdk?: string;
+  /**
+   * SDK Version
+   */
+  sdkv?: string;
+  payload: Record<string, string | number | boolean>;
+};
+
+/**
+ * @internal
+ */
+export type TelemetryEventRaw<Payload = TelemetryEvent['payload']> = {
+  event: TelemetryEvent['event'];
+  eventSamplingRate?: number;
+  payload: Payload;
+};
+
+export interface TelemetryCollector {
+  isEnabled: boolean;
+  isDebug: boolean;
+  record(event: TelemetryEventRaw): void;
+}