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",

packages/clerk-js/bundlewatch.config.json

@@ -1,12 +1,12 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "622KB" },
+    { "path": "./dist/clerk.js", "maxSize": "624KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
-    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
-    { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
-    { "path": "./dist/ui-common*.js", "maxSize": "113KB" },
+    { "path": "./dist/clerk.legacy.browser.js", "maxSize": "118KB" },
+    { "path": "./dist/clerk.headless*.js", "maxSize": "59KB" },
+    { "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

@@ -161,6 +161,32 @@ type SetActiveHook = (intent?: 'sign-out') => void | Promise<void>;
 
 export type ClerkCoreBroadcastChannelEvent = { type: 'signout' };
 
+/**
+ * Interface for the debug logger with all available logging methods
+ */
+interface DebugLoggerInterface {
+  debug(message: string, context?: Record<string, unknown>, source?: string): void;
+  error(message: string, context?: Record<string, unknown>, source?: string): void;
+  info(message: string, context?: Record<string, unknown>, source?: string): void;
+  trace(message: string, context?: Record<string, unknown>, source?: string): void;
+  warn(message: string, context?: Record<string, unknown>, source?: string): void;
+}
+
+/**
+ * Type guard to check if an object implements the DebugLoggerInterface
+ */
+function _isDebugLogger(obj: unknown): obj is DebugLoggerInterface {
+  return (
+    typeof obj === 'object' &&
+    obj !== null &&
+    typeof (obj as DebugLoggerInterface).debug === 'function' &&
+    typeof (obj as DebugLoggerInterface).error === 'function' &&
+    typeof (obj as DebugLoggerInterface).info === 'function' &&
+    typeof (obj as DebugLoggerInterface).trace === 'function' &&
+    typeof (obj as DebugLoggerInterface).warn === 'function'
+  );
+}
+
 declare global {
   interface Window {
     Clerk?: Clerk;
@@ -199,8 +225,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;
@@ -212,6 +238,7 @@ export class Clerk implements ClerkInterface {
   public __internal_country?: string | null;
   public telemetry: TelemetryCollector | undefined;
   public readonly __internal_state: State = new State();
+  public debugLogger?: DebugLoggerInterface;
 
   protected internal_last_error: ClerkAPIError | null = null;
   // converted to protected environment to support `updateEnvironment` type assertion
@@ -1509,6 +1536,7 @@ export class Clerk implements ClerkInterface {
     const customNavigate =
       options?.replace && this.#options.routerReplace ? this.#options.routerReplace : this.#options.routerPush;
 
+    this.debugLogger?.info(`Clerk is navigating to: ${toURL}`);
     if (this.#options.routerDebug) {
       console.log(`Clerk is navigating to: ${toURL}`);
     }
@@ -2233,6 +2261,23 @@ export class Clerk implements ClerkInterface {
 
   public updateEnvironment(environment: EnvironmentResource): asserts this is { environment: EnvironmentResource } {
     this.environment = environment;
+
+    // Initialize debug module if client_debug_mode is enabled
+    if (environment.clientDebugMode) {
+      this.#initializeDebugModule();
+    }
+  }
+
+  async #initializeDebugModule(): Promise<void> {
+    try {
+      const { getDebugLogger } = await import('./modules/debug');
+      const logger = await getDebugLogger({});
+      if (_isDebugLogger(logger)) {
+        this.debugLogger = logger;
+      }
+    } catch (error) {
+      console.error('Failed to initialize debug module:', error);
+    }
   }
 
   __internal_setCountry = (country: string | null) => {
@@ -2893,4 +2938,13 @@ export class Clerk implements ClerkInterface {
 
     return allowedProtocols;
   }
+
+  /**
+   * @internal
+   */
+  public static async __internal_resetDebugLogger(): Promise<void> {
+    // This method is now handled by the debug module itself
+    const { __internal_resetDebugLogger } = await import('./modules/debug');
+    __internal_resetDebugLogger();
+  }
 }