feat(clerk-js): Introduce debugLogger

.changeset/all-cougars-hide.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/types': patch
+---
+
+Introduce debugLogger for internal debugging support

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -125,6 +125,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/sign-up-resource.mdx",
   "types/signed-in-session-resource.mdx",
   "types/state-selectors.mdx",
+  "types/telemetry-log-entry.mdx",
   "types/use-auth-return.mdx",
   "types/use-session-list-return.mdx",
   "types/use-session-return.mdx",
@@ -148,6 +149,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "shared/derive-state.mdx",
   "shared/extract-dev-browser-jwt-from-url.mdx",
   "shared/fast-deep-merge-and-replace.mdx",
+  "shared/generate-uuid.mdx",
   "shared/get-clerk-js-major-version-or-tag.mdx",
   "shared/get-cookie-suffix.mdx",
   "shared/get-env-variable.mdx",

packages/clerk-js/bundlewatch.config.json

@@ -1,12 +1,12 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "625KB" },
+    { "path": "./dist/clerk.js", "maxSize": "626KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "78KB" },
-    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
+    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "119KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
-    { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
+    { "path": "./dist/ui-common*.js", "maxSize": "114KB" },
     { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "118KB" },
-    { "path": "./dist/vendors*.js", "maxSize": "40.2KB" },
+    { "path": "./dist/vendors*.js", "maxSize": "41KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
     { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },
     { "path": "./dist/createorganization*.js", "maxSize": "5KB" },

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

@@ -84,6 +84,9 @@ import type {
   Web3Provider,
 } from '@clerk/types';
 
+import type { DebugLoggerInterface } from '@/utils/debug';
+import { debugLogger, initDebugLogger } from '@/utils/debug';
+
 import type { MountComponentRenderer } from '../ui/Components';
 import {
   ALLOWED_PROTOCOLS,
@@ -159,6 +162,11 @@ type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
 
 export type ClerkCoreBroadcastChannelEvent = { type: 'signout' };
 
+/**
+ * Interface for the debug logger with all available logging methods
+ */
+// DebugLoggerInterface imported from '@/utils/debug'
+
 declare global {
   interface Window {
     Clerk?: Clerk;
@@ -197,8 +205,8 @@ export class Clerk implements ClerkInterface {
   public static sdkMetadata: SDKMetadata = {
     name: __PKG_NAME__,
     version: __PKG_VERSION__,
-    environment: process.env.NODE_ENV || 'production',
   };
+
   private static _billing: CommerceBillingNamespace;
   private static _apiKeys: APIKeysNamespace;
   private _checkout: ClerkInterface['__experimental_checkout'] | undefined;
@@ -210,6 +218,8 @@ export class Clerk implements ClerkInterface {
   public __internal_country?: string | null;
   public telemetry: TelemetryCollector | undefined;
   public readonly __internal_state: State = new State();
+  // Deprecated: use global singleton from `@/utils/debug`
+  public debugLogger?: DebugLoggerInterface;
 
   protected internal_last_error: ClerkAPIError | null = null;
   // converted to protected environment to support `updateEnvironment` type assertion
@@ -404,6 +414,7 @@ export class Clerk implements ClerkInterface {
   public getFapiClient = (): FapiClient => this.#fapiClient;
 
   public load = async (options?: ClerkOptions): Promise<void> => {
+    debugLogger.info('load() start', {}, 'clerk');
     if (this.loaded) {
       return;
     }
@@ -448,10 +459,18 @@ export class Clerk implements ClerkInterface {
       } else {
         await this.#loadInNonStandardBrowser();
       }
-    } catch (e) {
+      if (this.environment?.clientDebugMode) {
+        initDebugLogger({
+          enabled: true,
+          telemetryCollector: this.telemetry,
+        });
+      }
+      debugLogger.info('load() complete', {}, 'clerk');
+    } catch (error) {
       this.#publicEventBus.emit(clerkEvents.Status, 'error');
+      debugLogger.error('load() failed', { error }, 'clerk');
       // bubble up the error
-      throw e;
+      throw error;
     }
   };
 
@@ -477,6 +496,16 @@ export class Clerk implements ClerkInterface {
     const opts = callbackOrOptions && typeof callbackOrOptions === 'object' ? callbackOrOptions : options || {};
 
     const redirectUrl = opts?.redirectUrl || this.buildAfterSignOutUrl();
+    debugLogger.debug(
+      'signOut() start',
+      {
+        hasClient: Boolean(this.client),
+        multiSessionCount: this.client?.signedInSessions.length ?? 0,
+        redirectUrl,
+        sessionTarget: opts?.sessionId ?? null,
+      },
+      'clerk',
+    );
     const signOutCallback = typeof callbackOrOptions === 'function' ? callbackOrOptions : undefined;
 
     const executeSignOut = async () => {
@@ -520,6 +549,7 @@ export class Clerk implements ClerkInterface {
 
       await executeSignOut();
 
+      debugLogger.info('signOut() complete', { redirectUrl: stripOrigin(redirectUrl) }, 'clerk');
       return;
     }
 
@@ -531,6 +561,7 @@ export class Clerk implements ClerkInterface {
 
     if (shouldSignOutCurrent) {
       await executeSignOut();
+      debugLogger.info('signOut() complete', { redirectUrl: stripOrigin(redirectUrl) }, 'clerk');
     }
   };
 
@@ -1202,13 +1233,25 @@ export class Clerk implements ClerkInterface {
     const { organization, beforeEmit, redirectUrl, navigate: setActiveNavigate } = params;
     let { session } = params;
     this.__internal_setActiveInProgress = true;
-
+    debugLogger.debug(
+      'setActive() start',
+      {
+        hasClient: Boolean(this.client),
+        sessionTarget: typeof session === 'string' ? session : (session?.id ?? session ?? null),
+        organizationTarget:
+          typeof organization === 'string' ? organization : (organization?.id ?? organization ?? null),
+        redirectUrl: redirectUrl ?? null,
+      },
+      'clerk',
+    );
     try {
       if (!this.client) {
+        debugLogger.warn('Clerk setActive called before client is loaded', {}, 'clerk');
         throw new Error('setActive is being called before the client is loaded. Wait for init.');
       }
 
       if (session === undefined && !this.session) {
+        debugLogger.warn('Clerk setActive precondition not met: no target session and no active session', {}, 'clerk');
         throw new Error(
           'setActive should either be called with a session param or there should be already an active session.',
         );
@@ -1414,6 +1457,7 @@ export class Clerk implements ClerkInterface {
     const customNavigate =
       options?.replace && this.#options.routerReplace ? this.#options.routerReplace : this.#options.routerPush;
 
+    debugLogger.info(`Clerk is navigating to: ${toURL}`);
     if (this.#options.routerDebug) {
       console.log(`Clerk is navigating to: ${toURL}`);
     }

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

@@ -3,6 +3,8 @@ import { retry } from '@clerk/shared/retry';
 import { camelToSnake } from '@clerk/shared/underscore';
 import type { ClerkAPIErrorJSON, ClientJSON, InstanceType } from '@clerk/types';
 
+import { debugLogger } from '@/utils/debug';
+
 import { buildEmailAddress as buildEmailAddressUtil, buildURL as buildUrlUtil, stringifyQueryParams } from '../utils';
 import { SUPPORTED_FAPI_VERSION } from './constants';
 import { clerkNetworkError } from './errors';
@@ -250,12 +252,16 @@ export function createFapiClient(options: FapiClientOptions): FapiClient {
         response = new Response('{}', requestInit); // Mock an empty json response
       }
     } catch (e) {
+      debugLogger.error('network error', { error: e, url: urlStr, method }, 'fapiClient');
       clerkNetworkError(urlStr, e);
     }
 
     // 204 No Content responses do not have a body so we should not try to parse it
     const json: FapiResponseJSON<T> | null = response.status !== 204 ? await response.json() : null;
     const fapiResponse: FapiResponse<T> = Object.assign(response, { payload: json });
+    if (!response.ok) {
+      debugLogger.error('request failed', { method, path: requestInit.path, status: response.status }, 'fapiClient');
+    }
     await runAfterResponseCallbacks(requestInit, fapiResponse);
     return fapiResponse;
   }