@tracelog/lib 0.0.8 → 0.2.0

package/dist/esm/types/api.types.d.ts

@@ -2,20 +2,35 @@
  * Special project IDs for testing and development
  *
  * Both automatically force mode: 'debug' but differ in HTTP behavior:
- * - HttpSkip: NO network calls (pure offline testing)
- * - HttpLocal: Makes network calls to local server (integration testing)
+ * - Skip: NO network calls (pure offline testing)
+ * - Localhost: Makes network calls to local server (integration testing)
  */
 export declare enum SpecialProjectId {
     /**
+     * Value: 'skip'
+     *
      * Skips ALL HTTP calls - no config fetch, no event sending
      * Uses default local config, forces debug mode
      * Perfect for pure offline E2E testing
+     *
+     * @example
+     * await TraceLog.init({ id: SpecialProjectId.Skip });
+     * // or
+     * await TraceLog.init({ id: 'skip' });
      */
-    HttpSkip = "http-skip",
+    Skip = "skip",
     /**
-     * Makes HTTP calls to window.location.origin instead of production API
-     * Fetches config and sends events to local server, forces debug mode
+     * Value: 'localhost:' (used as prefix)
+     *
+     * Makes HTTP calls to local development server
+     * Must specify full address: 'localhost:PORT' (e.g., 'localhost:3000')
+     * Converts to http://localhost:PORT/config for requests
+     * Requires origin to be in ALLOWED_ORIGINS list, forces debug mode
      * Perfect for local development with running middleware
+     *
+     * @example
+     * await TraceLog.init({ id: 'localhost:3000' });
+     * // Makes requests to: http://localhost:3000/config
      */
-    HttpLocal = "http-local"
+    Localhost = "localhost:"
 }

package/dist/esm/types/api.types.js

@@ -2,21 +2,36 @@
  * Special project IDs for testing and development
  *
  * Both automatically force mode: 'debug' but differ in HTTP behavior:
- * - HttpSkip: NO network calls (pure offline testing)
- * - HttpLocal: Makes network calls to local server (integration testing)
+ * - Skip: NO network calls (pure offline testing)
+ * - Localhost: Makes network calls to local server (integration testing)
  */
 export var SpecialProjectId;
 (function (SpecialProjectId) {
     /**
+     * Value: 'skip'
+     *
      * Skips ALL HTTP calls - no config fetch, no event sending
      * Uses default local config, forces debug mode
      * Perfect for pure offline E2E testing
+     *
+     * @example
+     * await TraceLog.init({ id: SpecialProjectId.Skip });
+     * // or
+     * await TraceLog.init({ id: 'skip' });
      */
-    SpecialProjectId["HttpSkip"] = "http-skip";
+    SpecialProjectId["Skip"] = "skip";
     /**
-     * Makes HTTP calls to window.location.origin instead of production API
-     * Fetches config and sends events to local server, forces debug mode
+     * Value: 'localhost:' (used as prefix)
+     *
+     * Makes HTTP calls to local development server
+     * Must specify full address: 'localhost:PORT' (e.g., 'localhost:3000')
+     * Converts to http://localhost:PORT/config for requests
+     * Requires origin to be in ALLOWED_ORIGINS list, forces debug mode
      * Perfect for local development with running middleware
+     *
+     * @example
+     * await TraceLog.init({ id: 'localhost:3000' });
+     * // Makes requests to: http://localhost:3000/config
      */
-    SpecialProjectId["HttpLocal"] = "http-local";
+    SpecialProjectId["Localhost"] = "localhost:";
 })(SpecialProjectId || (SpecialProjectId = {}));

package/dist/esm/types/config.types.d.ts

@@ -1,103 +1,41 @@
 import { MetadataType } from './common.types';
 import { TagConfig } from './tag.types';
 import { Mode } from './mode.types';
-export type Config = ApiConfig & AppConfig;
-export interface ApiConfig {
-    /**
-     * Logging mode for the library.
-     * - 'qa': Shows client-facing logs only (INFO, CLIENT_WARN, CLIENT_ERROR)
-     * - 'debug': Shows all logs including internal library errors
-     */
-    mode?: Mode;
-    /**
-     * Sampling rate as a percentage (0-1) to control how many events are sent.
-     * A value of 1 means all events are sent, while 0.5 means only half of events are sent.
-     */
-    samplingRate?: number;
-    /**
-     * Array of tag configurations for categorizing and filtering events.
-     * Tags help organize and segment tracking data for analysis.
-     */
+export type Config = AppConfig & ExclusiveApiConfig;
+export type ApiConfig = SharedConfig & ExclusiveApiConfig;
+export type SharedConfig = Pick<AppConfig, 'mode' | 'samplingRate' | 'excludedUrlPaths'>;
+export interface ExclusiveApiConfig {
+    /** Tag definitions used to categorize tracked events. */
     tags?: TagConfig[];
-    /**
-     * Array of URL path patterns to exclude from tracking.
-     * Events will not be sent for pages matching these patterns.
-     */
-    excludedUrlPaths?: string[];
-    /**
-     * Flag to indicate if IP addresses should be excluded from tracking.
-     * When true, IP addresses will not be collected or sent with events.
-     * This is useful for privacy compliance and reducing data exposure.
-     */
+    /** Determines if IP address is excluded from tracking. */
     ipExcluded?: boolean;
 }
 export interface AppConfig {
-    /**
-     * Unique project identifier.
-     */
+    /** Project identifier used for tracing. */
     id: string;
-    /**
-     * Session timeout in milliseconds. After this period of inactivity,
-     * a new session will be started for subsequent events.
-     *
-     * **Timeout Guidelines:**
-     * - **15 minutes (default)**: Recommended for most applications, aligns with security best practices
-     * - **30 minutes**: Standard for content-heavy sites (matches Google Analytics default)
-     * - **45-60 minutes**: Consider for sites with long-form content, videos, or documentation
-     * - **5-10 minutes**: Use for security-sensitive applications requiring frequent re-authentication
-     *
-     * **Impact on Analytics:**
-     * - Shorter timeouts = Higher session count, higher bounce rate, potentially lower conversion rates
-     * - Longer timeouts = Lower session count, more accurate user journey tracking, better conversion attribution
-     *
-     * **When to Adjust:**
-     * - Match your application's auto-logout timeout if applicable
-     * - Increase for content where users frequently pause (tutorials, long articles, videos)
-     * - Decrease for applications with sensitive data or frequent security requirements
-     * - Monitor bounce rates and conversion funnels when changing this value
-     *
-     * @default 900000 (15 minutes)
-     * @min 30000 (30 seconds)
-     * @max 86400000 (24 hours)
-     */
+    /** Session inactivity timeout in milliseconds. @default 900000 */
     sessionTimeout?: number;
-    /**
-     * Metadata that will be automatically attached to all tracking events.
-     * These key-value pairs provide additional context for every event sent.
-     */
+    /** Metadata appended to every tracked event. */
     globalMetadata?: Record<string, MetadataType>;
-    /**
-     * CSS selectors for custom scroll containers. Can be a single selector string
-     * or an array of selectors. Used to track scroll events within specific elements
-     * instead of the default window scroll.
-     */
+    /** Selectors defining custom scroll containers to monitor. */
     scrollContainerSelectors?: string | string[];
-    /**
-     * Allow HTTP requests to be made. This is useful for testing and development.
-     */
+    /** Enables HTTP requests for testing and development flows. */
     allowHttp?: boolean;
-    /**
-     * Array of query parameters to be removed from the URL.
-     */
+    /** Query parameters to remove before tracking URLs. */
     sensitiveQueryParams?: string[];
-    /**
-     * Sampling rate for error events (0-1).
-     * Controls how many error and network error events are captured.
-     * @default 0.1 for production, 1.0 for qa/debug mode
-     */
+    /** Error event sampling rate between 0 and 1. */
     errorSampling?: number;
-    /**
-     * Optional integrations configuration.
-     */
+    /** Logging mode controlling verbosity of client logs. */
+    mode?: Mode;
+    /** Event sampling rate between 0 and 1. */
+    samplingRate?: number;
+    /** URL path patterns that should be ignored by tracking. */
+    excludedUrlPaths?: string[];
+    /** Optional configuration for third-party integrations. */
     integrations?: {
-        /**
-         * Google Analytics integration configuration.
-         */
+        /** Google Analytics integration options. */
         googleAnalytics?: {
-            /**
-             * Google Analytics measurement ID.
-             * Required for initializing the Google Analytics integration.
-             */
+            /** Required measurement ID for Google Analytics. */
             measurementId: string;
         };
     };

package/dist/esm/types/emitter.types.d.ts

@@ -0,0 +1,11 @@
+import { EventData } from './event.types';
+import { BaseEventsQueueDto } from './queue.types';
+export type EmitterCallback<T = any> = (data: T) => void;
+export declare enum EmitterEvent {
+    EVENT = "event",
+    QUEUE = "queue"
+}
+export interface EmitterMap {
+    [EmitterEvent.EVENT]: EventData;
+    [EmitterEvent.QUEUE]: BaseEventsQueueDto;
+}

package/dist/esm/types/emitter.types.js

@@ -0,0 +1,5 @@
+export var EmitterEvent;
+(function (EmitterEvent) {
+    EmitterEvent["EVENT"] = "event";
+    EmitterEvent["QUEUE"] = "queue";
+})(EmitterEvent || (EmitterEvent = {}));

package/dist/esm/types/event.types.d.ts

@@ -40,12 +40,7 @@ export interface ClickData {
     ariaLabel?: string;
     dataAttributes?: Record<string, string>;
 }
-export interface ClickCoordinates {
-    x: number;
-    y: number;
-    relativeX: number;
-    relativeY: number;
-}
+export type ClickCoordinates = Pick<ClickData, 'x' | 'y' | 'relativeX' | 'relativeY'>;
 export interface ClickTrackingElementData {
     element: HTMLElement;
     name: string;
@@ -62,11 +57,9 @@ export interface WebVitalsData {
 export interface ErrorData {
     type: ErrorType;
     message: string;
-    method?: string;
-    url?: string;
-    status?: number;
-    statusText?: string;
-    duration?: number;
+    filename?: string;
+    line?: number;
+    column?: number;
 }
 export interface UTM {
     source?: string;
@@ -82,6 +75,10 @@ export interface PageViewData {
     search?: string;
     hash?: string;
 }
+export interface VitalSample {
+    type: WebVitalType;
+    value: number;
+}
 export interface EventData {
     type: EventType;
     page_url: string;

package/dist/esm/types/index.d.ts

@@ -2,12 +2,14 @@ export * from './api.types';
 export * from './common.types';
 export * from './config.types';
 export * from './device.types';
+export * from './emitter.types';
 export * from './event.types';
 export * from './log.types';
 export * from './mode.types';
 export * from './queue.types';
+export * from './session.types';
 export * from './state.types';
 export * from './tag.types';
+export * from './test-bridge.types';
 export * from './validation-error.types';
-export * from './web-vitals.types';
 export * from './window.types';

package/dist/esm/types/index.js

@@ -2,12 +2,14 @@ export * from './api.types';
 export * from './common.types';
 export * from './config.types';
 export * from './device.types';
+export * from './emitter.types';
 export * from './event.types';
 export * from './log.types';
 export * from './mode.types';
 export * from './queue.types';
+export * from './session.types';
 export * from './state.types';
 export * from './tag.types';
+export * from './test-bridge.types';
 export * from './validation-error.types';
-export * from './web-vitals.types';
 export * from './window.types';

package/dist/esm/types/queue.types.d.ts

@@ -20,4 +20,5 @@ export interface PersistedQueueData {
     events: BaseEventsQueueDto['events'];
     timestamp: number;
     global_metadata?: BaseEventsQueueDto['global_metadata'];
+    fallbackMode?: boolean;
 }

package/dist/esm/types/session.types.d.ts

@@ -1,65 +1 @@
 export type SessionEndReason = 'inactivity' | 'page_unload' | 'manual_stop' | 'orphaned_cleanup' | 'tab_closed';
-export interface SessionEndConfig {
-    enablePageUnloadHandlers: boolean;
-    syncTimeoutMs: number;
-    maxRetries: number;
-    debugMode: boolean;
-}
-export interface SessionEndResult {
-    success: boolean;
-    reason: SessionEndReason;
-    timestamp: number;
-    eventsFlushed: number;
-    method: 'async' | 'sync';
-}
-export interface SessionEndStats {
-    totalSessionEnds: number;
-    successfulEnds: number;
-    failedEnds: number;
-    duplicatePrevented: number;
-    reasonCounts: Record<SessionEndReason, number>;
-}
-export interface CrossTabSessionConfig {
-    tabHeartbeatIntervalMs: number;
-    tabElectionTimeoutMs: number;
-    debugMode: boolean;
-}
-export interface TabInfo {
-    id: string;
-    lastHeartbeat: number;
-    isLeader: boolean;
-    sessionId: string;
-    startTime: number;
-}
-export interface CrossTabMessage {
-    type: 'heartbeat' | 'session_start' | 'session_end' | 'tab_closing' | 'election_request' | 'election_response';
-    tabId: string;
-    sessionId?: string;
-    timestamp: number;
-    data?: Record<string, unknown>;
-}
-export interface SessionRecoveryConfig {
-    recoveryWindowMs: number;
-    maxRecoveryAttempts: number;
-    contextPreservation: boolean;
-}
-export interface SessionContext {
-    sessionId: string;
-    startTime: number;
-    lastActivity: number;
-    tabCount: number;
-    recoveryAttempts: number;
-    metadata?: Record<string, unknown>;
-}
-export interface RecoveryAttempt {
-    sessionId: string;
-    timestamp: number;
-    attempt: number;
-    context: SessionContext;
-}
-export interface SessionHealth {
-    recoveryAttempts: number;
-    sessionTimeouts: number;
-    crossTabConflicts: number;
-    lastHealthCheck: number;
-}

package/dist/esm/types/state.types.d.ts

@@ -9,4 +9,5 @@ export interface State {
     pageUrl: string;
     hasStartSession: boolean;
     suppressNextScroll: boolean;
+    scrollEventCount?: number;
 }

package/dist/esm/types/test-bridge.types.d.ts

@@ -0,0 +1,38 @@
+import { ClickHandler } from '@/handlers/click.handler';
+import { ErrorHandler } from '@/handlers/error.handler';
+import { PageViewHandler } from '@/handlers/page-view.handler';
+import { PerformanceHandler } from '@/handlers/performance.handler';
+import { ScrollHandler } from '@/handlers/scroll.handler';
+import { SessionHandler } from '@/handlers/session.handler';
+import { GoogleAnalyticsIntegration } from '@/integrations/google-analytics.integration';
+import { EventManager } from '@/managers/event.manager';
+import { StorageManager as TraceLogStorageManager } from '@/managers/storage.manager';
+import { AppConfig } from './config.types';
+import { State } from './state.types';
+/**
+ * Testing bridge interface for E2E tests
+ * Only available when NODE_ENV=dev
+ */
+export interface TraceLogTestBridge {
+    readonly initialized: boolean;
+    init(config: AppConfig): Promise<void>;
+    destroy(): Promise<void>;
+    isInitializing(): boolean;
+    sendCustomEvent(name: string, data?: Record<string, unknown>): void;
+    on(event: string, callback: (data: any) => void): void;
+    off(event: string, callback: (data: any) => void): void;
+    getSessionData(): Record<string, unknown> | null;
+    setSessionTimeout(timeout: number): void;
+    getQueueLength(): number;
+    forceInitLock(enabled?: boolean): void;
+    get<T extends keyof State>(key: T): State[T];
+    getStorageManager(): TraceLogStorageManager | null;
+    getEventManager(): EventManager | null;
+    getSessionHandler(): SessionHandler | null;
+    getPageViewHandler(): PageViewHandler | null;
+    getClickHandler(): ClickHandler | null;
+    getScrollHandler(): ScrollHandler | null;
+    getPerformanceHandler(): PerformanceHandler | null;
+    getErrorHandler(): ErrorHandler | null;
+    getGoogleAnalytics(): GoogleAnalyticsIntegration | null;
+}

package/dist/esm/types/validation-error.types.d.ts

@@ -40,3 +40,10 @@ export declare class SamplingRateValidationError extends TraceLogValidationError
 export declare class IntegrationValidationError extends TraceLogValidationError {
     constructor(message: string, layer?: 'config' | 'app' | 'runtime');
 }
+/**
+ * Thrown when initialization exceeds the maximum allowed timeout
+ */
+export declare class InitializationTimeoutError extends TraceLogValidationError {
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, layer?: 'config' | 'app' | 'runtime');
+}

package/dist/esm/types/validation-error.types.js

@@ -57,3 +57,12 @@ export class IntegrationValidationError extends TraceLogValidationError {
         super(message, 'INTEGRATION_INVALID', layer);
     }
 }
+/**
+ * Thrown when initialization exceeds the maximum allowed timeout
+ */
+export class InitializationTimeoutError extends TraceLogValidationError {
+    constructor(message, timeoutMs, layer = 'runtime') {
+        super(message, 'INITIALIZATION_TIMEOUT', layer);
+        this.timeoutMs = timeoutMs;
+    }
+}

package/dist/esm/types/window.types.d.ts

@@ -1,11 +1,4 @@
-import type { App } from '../app';
-/**
- * Testing bridge interface for E2E tests
- * Only available when NODE_ENV=dev
- */
-export interface TraceLogTestBridge extends App {
-    isInitializing(): boolean;
-}
+import { TraceLogTestBridge } from './test-bridge.types';
 declare global {
     interface Window {
         /**

package/dist/esm/utils/data/uuid.utils.d.ts

@@ -1,5 +1,5 @@
 /**
- * Generates a RFC4122 compliant UUID v4
+ * Generates a RFC4122 compliant UUID v4 using native crypto API with fallback
  * @returns A UUID string
  */
 export declare const generateUUID: () => string;

package/dist/esm/utils/data/uuid.utils.js

@@ -1,14 +1,16 @@
-import { debugLog } from '../logging';
 /**
- * Generates a RFC4122 compliant UUID v4
+ * Generates a RFC4122 compliant UUID v4 using native crypto API with fallback
  * @returns A UUID string
  */
 export const generateUUID = () => {
-    const uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    // Use native crypto.randomUUID() if available (modern browsers)
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback for older browsers
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
         const r = (Math.random() * 16) | 0;
         const v = c === 'x' ? r : (r & 0x3) | 0x8;
         return v.toString(16);
     });
-    debugLog.verbose('UUIDUtils', 'Generated new UUID', { uuid });
-    return uuid;
 };

package/dist/esm/utils/emitter.utils.d.ts

@@ -0,0 +1,8 @@
+import { EmitterCallback, EmitterMap } from '@/types';
+export declare class Emitter {
+    private readonly listeners;
+    on<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;
+    off<K extends keyof EmitterMap>(event: K, callback: EmitterCallback<EmitterMap[K]>): void;
+    emit<K extends keyof EmitterMap>(event: K, data: EmitterMap[K]): void;
+    removeAllListeners(): void;
+}

package/dist/esm/utils/emitter.utils.js

@@ -0,0 +1,29 @@
+export class Emitter {
+    constructor() {
+        this.listeners = new Map();
+    }
+    on(event, callback) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, []);
+        }
+        this.listeners.get(event).push(callback);
+    }
+    off(event, callback) {
+        const callbacks = this.listeners.get(event);
+        if (callbacks) {
+            const index = callbacks.indexOf(callback);
+            if (index > -1) {
+                callbacks.splice(index, 1);
+            }
+        }
+    }
+    emit(event, data) {
+        const callbacks = this.listeners.get(event);
+        if (callbacks) {
+            callbacks.forEach((callback) => callback(data));
+        }
+    }
+    removeAllListeners() {
+        this.listeners.clear();
+    }
+}

package/dist/esm/utils/index.d.ts

@@ -4,3 +4,4 @@ export * from './logging';
 export * from './network';
 export * from './security';
 export * from './validations';
+export * from './emitter.utils';

package/dist/esm/utils/index.js

@@ -4,3 +4,4 @@ export * from './logging';
 export * from './network';
 export * from './security';
 export * from './validations';
+export * from './emitter.utils';

package/dist/esm/utils/logging/debug-logger.utils.d.ts

@@ -1,56 +1,15 @@
 import { StateManager } from '../../managers/state.manager';
-/**
- * Debug logger class that extends StateManager for clean access to global state
- */
 declare class DebugLogger extends StateManager {
-    /**
-     * Client-facing error - Configuration/usage errors by the client
-     * Console: qa and debug modes | Events: NODE_ENV=dev
-     */
-    clientError(namespace: string, message: string, data?: unknown): void;
-    /**
-     * Client-facing warning - Configuration/usage warnings by the client
-     * Console: qa and debug modes | Events: NODE_ENV=dev
-     */
-    clientWarn(namespace: string, message: string, data?: unknown): void;
-    /**
-     * General operational information
-     * Console: qa and debug modes | Events: NODE_ENV=dev
-     */
-    info(namespace: string, message: string, data?: unknown): void;
-    /**
-     * Internal library errors
-     * Console: debug mode only | Events: NODE_ENV=dev
-     */
-    error(namespace: string, message: string, data?: unknown): void;
-    /**
-     * Internal library warnings
-     * Console: debug mode only | Events: NODE_ENV=dev
-     */
-    warn(namespace: string, message: string, data?: unknown): void;
-    /**
-     * Strategic debug information
-     * Console: debug mode only | Events: NODE_ENV=dev
-     */
-    debug(namespace: string, message: string, data?: unknown): void;
-    /**
-     * Detailed trace information
-     * Console: debug mode only | Events: NODE_ENV=dev
-     */
-    verbose(namespace: string, message: string, data?: unknown): void;
-    private getCurrentMode;
-    private shouldShowLog;
-    private formatMessage;
-    private getConsoleMethod;
-    private logMessage;
-    /**
-     * Dispatches tracelog:log events for E2E testing and development debugging
-     */
-    private dispatchEvent;
+    clientError: (ns: string, msg: string, data?: unknown) => void;
+    clientWarn: (ns: string, msg: string, data?: unknown) => void;
+    info: (ns: string, msg: string, data?: unknown) => void;
+    error: (ns: string, msg: string, data?: unknown) => void;
+    warn: (ns: string, msg: string, data?: unknown) => void;
+    debug: (ns: string, msg: string, data?: unknown) => void;
+    verbose: (ns: string, msg: string, data?: unknown) => void;
+    private log;
+    private shouldShow;
+    private getMethod;
 }
-/**
- * Singleton debug logger instance
- * Provides the same API as before: debugLog.clientError(), debugLog.info(), etc.
- */
 export declare const debugLog: DebugLogger;
 export {};