refactor(core): Logger abstraction added

Author: Reversean

packages/core/src/index.ts

@@ -1,3 +1,5 @@
 export type { HawkStorage } from './storages/hawk-storage';
 export type { UserManager } from './users/user-manager';
 export { HawkStorageUserManager } from './users/hawk-storage-user-manager';
+export type { Logger, LogType } from './logger/logger';
+export { setLogger, log } from './logger/logger';

packages/core/src/logger/logger.ts

@@ -0,0 +1,54 @@
+/**
+ * Log level type for categorizing log messages.
+ *
+ * Includes standard console methods supported in both browser and Node.js:
+ * - Standard levels: `log`, `warn`, `error`, `info`
+ * - Performance timing: `time`, `timeEnd`
+ */
+export type LogType = 'log' | 'warn' | 'error' | 'info' | 'time' | 'timeEnd';
+
+/**
+ * Logger function interface for environment-specific logging implementations.
+ *
+ * Implementations should handle message formatting, output styling,
+ * and platform-specific logging mechanisms (e.g., console, file, network).
+ *
+ * @param msg - The message to log.
+ * @param type - Log level/severity (default: 'log').
+ * @param args - Additional data to include with the log message.
+ */
+export interface Logger {
+  (msg: string, type?: LogType, args?: unknown): void;
+}
+
+/**
+ * Global logger instance, set by environment-specific packages.
+ */
+let loggerInstance: Logger | null = null;
+
+/**
+ * Registers the environment-specific logger implementation.
+ *
+ * This should be called once during application initialization
+ * by the environment-specific package.
+ *
+ * @param logger - Logger implementation to use globally.
+ */
+export function setLogger(logger: Logger): void {
+  loggerInstance = logger;
+}
+
+/**
+ * Logs a message using the registered logger implementation.
+ *
+ * If no logger has been registered via {@link setLogger}, this is a no-op.
+ *
+ * @param msg - Message to log.
+ * @param type - Log level (default: 'log').
+ * @param args - Additional arguments to log.
+ */
+export function log(msg: string, type?: LogType, args?: unknown): void {
+  if (loggerInstance) {
+    loggerInstance(msg, type, args);
+  }
+}

packages/javascript/src/addons/breadcrumbs.ts

@@ -4,7 +4,7 @@
 import type { Breadcrumb, BreadcrumbLevel, BreadcrumbType, Json, JsonNode } from '@hawk.so/types';
 import Sanitizer from '../modules/sanitizer';
 import { buildElementSelector } from '../utils/selector';
-import log from '../utils/log';
+import { log } from '@hawk.so/core';
 import { isValidBreadcrumb } from '../utils/validation';
 
 /**

packages/javascript/src/catcher.ts

@@ -1,6 +1,5 @@
 import Socket from './modules/socket';
 import Sanitizer from './modules/sanitizer';
-import log from './utils/log';
 import StackParser from './modules/stackParser';
 import type { CatcherMessage, HawkInitialSettings, BreadcrumbsAPI, Transport } from './types';
 import { VueIntegration } from './integrations/vue';
@@ -18,9 +17,9 @@ import { isErrorProcessed, markErrorAsProcessed } from './utils/event';
 import { ConsoleCatcher } from './addons/consoleCatcher';
 import { BreadcrumbManager } from './addons/breadcrumbs';
 import { validateUser, validateContext, isValidEventPayload } from './utils/validation';
-import type { UserManager } from '@hawk.so/core';
-import { HawkStorageUserManager } from '@hawk.so/core';
+import { HawkStorageUserManager, UserManager, setLogger, log } from '@hawk.so/core';
 import { HawkLocalStorage } from './storages/hawk-local-storage';
+import { createBrowserLogger } from './logger/logger';
 import { id } from './utils/id';
 
 /**
@@ -120,6 +119,8 @@ export default class Catcher {
    * @param {HawkInitialSettings|string} settings - If settings is a string, it means an Integration Token
    */
   constructor(settings: HawkInitialSettings | string) {
+    setLogger(createBrowserLogger(VERSION));
+
     if (typeof settings === 'string') {
       settings = {
         token: settings,

packages/javascript/src/logger/logger.ts

@@ -0,0 +1,61 @@
+import type { Logger, LogType } from '@hawk.so/core';
+
+/**
+ * Creates a browser console logger with Hawk branding and styled output.
+ *
+ * The logger outputs to `window.console` with a dark label badge
+ * containing the Hawk version. Messages are formatted with CSS
+ * styling for better visibility in browser developer tools.
+ *
+ * @param version - Version string to display in log messages.
+ * @param style - Optional CSS style for the message text (default: 'color: inherit').
+ * @returns {Logger} Logger function implementation for browser environments.
+ *
+ * @example
+ * ```TypeScript
+ * import { createBrowserLogger } from '@hawk.so/browser';
+ * import { setLogger } from '@hawk.so/core';
+ *
+ * const logger = createBrowserLogger('3.2.0');
+ * setLogger(logger);
+ *
+ * // Custom styling
+ * const styledLogger = createBrowserLogger('3.2.0', 'color: blue; font-weight: bold');
+ * ```
+ */
+export function createBrowserLogger(version: string, style = 'color: inherit'): Logger {
+  return (msg: string, type: LogType = 'log', args?: unknown): void => {
+    if (!('console' in window)) {
+      return;
+    }
+
+    const editorLabelText = `Hawk (${version})`;
+    const editorLabelStyle = `line-height: 1em;
+            color: #fff;
+            display: inline-block;
+            line-height: 1em;
+            background-color: rgba(0,0,0,.7);
+            padding: 3px 5px;
+            border-radius: 3px;
+            margin-right: 2px`;
+
+    try {
+      switch (type) {
+        case 'time':
+        case 'timeEnd':
+          console[type](`( ${editorLabelText} ) ${msg}`);
+          break;
+        case 'log':
+        case 'warn':
+        case 'error':
+        case 'info':
+          if (args !== undefined) {
+            console[type](`%c${editorLabelText}%c ${msg} %o`, editorLabelStyle, style, args);
+          } else {
+            console[type](`%c${editorLabelText}%c ${msg}`, editorLabelStyle, style);
+          }
+          break;
+      }
+    } catch (ignored) {}
+  };
+}

packages/javascript/src/modules/fetchTimer.ts

@@ -1,4 +1,4 @@
-import log from '../utils/log';
+import { log } from '@hawk.so/core';
 
 /**
  * Sends AJAX request and wait for some time.

packages/javascript/src/modules/socket.ts

@@ -1,4 +1,4 @@
-import log from '../utils/log';
+import { log } from '@hawk.so/core';
 import type { CatcherMessage } from '@/types';
 import type { Transport } from '../types/transport';
 

packages/javascript/src/utils/event.ts

@@ -1,4 +1,4 @@
-import log from './log';
+import { log } from '@hawk.so/core';
 
 /**
  * Symbol to mark error as processed by Hawk

packages/javascript/src/utils/log.ts

@@ -1,4 +1,4 @@
-import log from './log';
+import { log } from '@hawk.so/core';
 import type { AffectedUser, Breadcrumb, EventContext, EventData, JavaScriptAddons } from '@hawk.so/types';
 import Sanitizer from '../modules/sanitizer';