@tracelog/lib 0.0.1

package/dist/cjs/utils/validations/event-validations.utils.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEventValid = void 0;
+const metadata_validations_utils_1 = require("./metadata-validations.utils");
+const logging_1 = require("../logging");
+/**
+ * Validates a complete event with name and optional metadata
+ * @param eventName - The event name to validate
+ * @param metadata - Optional metadata to validate
+ * @returns Validation result with sanitized metadata if valid
+ */
+const isEventValid = (eventName, metadata) => {
+    const nameValidation = (0, metadata_validations_utils_1.isValidEventName)(eventName);
+    if (!nameValidation.valid) {
+        logging_1.debugLog.clientError('EventValidation', 'Event name validation failed', { eventName, error: nameValidation.error });
+        return nameValidation;
+    }
+    if (!metadata) {
+        return { valid: true };
+    }
+    const metadataValidation = (0, metadata_validations_utils_1.isValidMetadata)(eventName, metadata, 'customEvent');
+    if (!metadataValidation.valid) {
+        logging_1.debugLog.clientError('EventValidation', 'Event metadata validation failed', {
+            eventName,
+            error: metadataValidation.error,
+        });
+    }
+    return metadataValidation;
+};
+exports.isEventValid = isEventValid;

package/dist/cjs/utils/validations/index.d.ts

@@ -0,0 +1,5 @@
+export * from './config-validations.utils';
+export * from './event-validations.utils';
+export * from './metadata-validations.utils';
+export * from './type-guards.utils';
+export * from './url-validations.utils';

package/dist/cjs/utils/validations/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./config-validations.utils"), exports);
+__exportStar(require("./event-validations.utils"), exports);
+__exportStar(require("./metadata-validations.utils"), exports);
+__exportStar(require("./type-guards.utils"), exports);
+__exportStar(require("./url-validations.utils"), exports);

package/dist/cjs/utils/validations/metadata-validations.utils.d.ts

@@ -0,0 +1,22 @@
+import { MetadataType } from '../../types';
+/**
+ * Validates an event name
+ * @param eventName - The event name to validate
+ * @returns Validation result with error message if invalid
+ */
+export declare const isValidEventName: (eventName: string) => {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Validates metadata for events
+ * @param eventName - The event name (for error messages)
+ * @param metadata - The metadata to validate
+ * @param type - Type of metadata (globalMetadata or customEvent)
+ * @returns Validation result with sanitized metadata if valid
+ */
+export declare const isValidMetadata: (eventName: string, metadata: Record<string, unknown>, type?: "globalMetadata" | "customEvent") => {
+    valid: boolean;
+    error?: string;
+    sanitizedMetadata?: Record<string, MetadataType>;
+};

package/dist/cjs/utils/validations/metadata-validations.utils.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidMetadata = exports.isValidEventName = void 0;
+const constants_1 = require("../../constants");
+const sanitize_utils_1 = require("../security/sanitize.utils");
+const type_guards_utils_1 = require("./type-guards.utils");
+/**
+ * Validates an event name
+ * @param eventName - The event name to validate
+ * @returns Validation result with error message if invalid
+ */
+const isValidEventName = (eventName) => {
+    if (typeof eventName !== 'string') {
+        return {
+            valid: false,
+            error: 'Event name must be a string',
+        };
+    }
+    if (eventName.length === 0) {
+        return {
+            valid: false,
+            error: 'Event name cannot be empty',
+        };
+    }
+    if (eventName.length > constants_1.MAX_CUSTOM_EVENT_NAME_LENGTH) {
+        return {
+            valid: false,
+            error: `Event name is too long (max ${constants_1.MAX_CUSTOM_EVENT_NAME_LENGTH} characters)`,
+        };
+    }
+    if (eventName.includes('<') || eventName.includes('>') || eventName.includes('&')) {
+        return {
+            valid: false,
+            error: 'Event name contains invalid characters',
+        };
+    }
+    const reservedWords = ['constructor', 'prototype', '__proto__', 'eval', 'function', 'var', 'let', 'const'];
+    if (reservedWords.includes(eventName.toLowerCase())) {
+        return {
+            valid: false,
+            error: 'Event name cannot be a reserved word',
+        };
+    }
+    return { valid: true };
+};
+exports.isValidEventName = isValidEventName;
+/**
+ * Validates metadata for events
+ * @param eventName - The event name (for error messages)
+ * @param metadata - The metadata to validate
+ * @param type - Type of metadata (globalMetadata or customEvent)
+ * @returns Validation result with sanitized metadata if valid
+ */
+const isValidMetadata = (eventName, metadata, type) => {
+    const sanitizedMetadata = (0, sanitize_utils_1.sanitizeMetadata)(metadata);
+    const intro = type && type === 'customEvent' ? `${type} "${eventName}" metadata error` : `${eventName} metadata error`;
+    if (!(0, type_guards_utils_1.isOnlyPrimitiveFields)(sanitizedMetadata)) {
+        return {
+            valid: false,
+            error: `${intro}: object has invalid types. Valid types are string, number, boolean or string arrays.`,
+        };
+    }
+    let jsonString;
+    try {
+        jsonString = JSON.stringify(sanitizedMetadata);
+    }
+    catch {
+        return {
+            valid: false,
+            error: `${intro}: object contains circular references or cannot be serialized.`,
+        };
+    }
+    if (jsonString.length > constants_1.MAX_CUSTOM_EVENT_STRING_SIZE) {
+        return {
+            valid: false,
+            error: `${intro}: object is too large (max ${constants_1.MAX_CUSTOM_EVENT_STRING_SIZE / 1024} KB).`,
+        };
+    }
+    const keyCount = Object.keys(sanitizedMetadata).length;
+    if (keyCount > constants_1.MAX_CUSTOM_EVENT_KEYS) {
+        return {
+            valid: false,
+            error: `${intro}: object has too many keys (max ${constants_1.MAX_CUSTOM_EVENT_KEYS} keys).`,
+        };
+    }
+    for (const [key, value] of Object.entries(sanitizedMetadata)) {
+        if (Array.isArray(value)) {
+            if (value.length > constants_1.MAX_CUSTOM_EVENT_ARRAY_SIZE) {
+                return {
+                    valid: false,
+                    error: `${intro}: array property "${key}" is too large (max ${constants_1.MAX_CUSTOM_EVENT_ARRAY_SIZE} items).`,
+                };
+            }
+            for (const item of value) {
+                if (typeof item === 'string' && item.length > 500) {
+                    return {
+                        valid: false,
+                        error: `${intro}: array property "${key}" contains strings that are too long (max 500 characters).`,
+                    };
+                }
+            }
+        }
+        if (typeof value === 'string' && value.length > constants_1.MAX_STRING_LENGTH) {
+            return {
+                valid: false,
+                error: `${intro}: property "${key}" is too long (max ${constants_1.MAX_STRING_LENGTH} characters).`,
+            };
+        }
+    }
+    return {
+        valid: true,
+        sanitizedMetadata,
+    };
+};
+exports.isValidMetadata = isValidMetadata;

package/dist/cjs/utils/validations/type-guards.utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks if an object contains only primitive fields (string, number, boolean, or string arrays)
+ * @param object - The object to check
+ * @returns True if the object contains only primitive fields
+ */
+export declare const isOnlyPrimitiveFields: (object: Record<string, unknown>) => boolean;

package/dist/cjs/utils/validations/type-guards.utils.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isOnlyPrimitiveFields = void 0;
+/**
+ * Checks if an object contains only primitive fields (string, number, boolean, or string arrays)
+ * @param object - The object to check
+ * @returns True if the object contains only primitive fields
+ */
+const isOnlyPrimitiveFields = (object) => {
+    if (typeof object !== 'object' || object === null) {
+        return false;
+    }
+    for (const value of Object.values(object)) {
+        if (value === null || value === undefined) {
+            continue;
+        }
+        const type = typeof value;
+        if (type === 'string' || type === 'number' || type === 'boolean') {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            if (!value.every((item) => typeof item === 'string')) {
+                return false;
+            }
+            continue;
+        }
+        return false;
+    }
+    return true;
+};
+exports.isOnlyPrimitiveFields = isOnlyPrimitiveFields;

package/dist/cjs/utils/validations/url-validations.utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Validates if a URL is valid and optionally allows HTTP URLs
+ * @param url - The URL to validate
+ * @param allowHttp - Whether to allow HTTP URLs (default: false)
+ * @returns True if the URL is valid, false otherwise
+ */
+export declare const isValidUrl: (url: string, allowHttp?: boolean) => boolean;
+/**
+ * Validates a URL field in configuration
+ * @param url - The URL to validate
+ * @param allowHttp - Whether to allow HTTP URLs
+ * @param fieldName - The name of the field being validated
+ * @param errors - Array to push errors to
+ */
+export declare const validateUrl: (url: unknown, allowHttp: boolean | undefined, fieldName: string, errors: string[]) => void;

package/dist/cjs/utils/validations/url-validations.utils.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateUrl = exports.isValidUrl = void 0;
+/**
+ * Validates if a URL is valid and optionally allows HTTP URLs
+ * @param url - The URL to validate
+ * @param allowHttp - Whether to allow HTTP URLs (default: false)
+ * @returns True if the URL is valid, false otherwise
+ */
+const isValidUrl = (url, allowHttp = false) => {
+    try {
+        const parsed = new URL(url);
+        const isHttps = parsed.protocol === 'https:';
+        const isHttp = parsed.protocol === 'http:';
+        return isHttps || (allowHttp && isHttp);
+    }
+    catch {
+        return false;
+    }
+};
+exports.isValidUrl = isValidUrl;
+/**
+ * Validates a URL field in configuration
+ * @param url - The URL to validate
+ * @param allowHttp - Whether to allow HTTP URLs
+ * @param fieldName - The name of the field being validated
+ * @param errors - Array to push errors to
+ */
+const validateUrl = (url, allowHttp, fieldName, errors) => {
+    if (url !== undefined) {
+        if (typeof url === 'string') {
+            try {
+                const parsed = new URL(url);
+                if (parsed.protocol === 'http:' && !allowHttp) {
+                    errors.push(`${fieldName} using http requires allowHttp=true`);
+                }
+            }
+            catch {
+                errors.push(`${fieldName} must be a valid URL`);
+            }
+        }
+        else {
+            errors.push(`${fieldName} must be a string`);
+        }
+    }
+};
+exports.validateUrl = validateUrl;

package/dist/esm/api.d.ts

@@ -0,0 +1,46 @@
+import { MetadataType } from './types/common.types';
+import { AppConfig } from './types/config.types';
+import './types/window.types';
+export * as Types from './app.types';
+export * as Constants from './app.constants';
+/**
+ * Initializes the tracelog app with the provided configuration.
+ * If already initialized, this function returns early without error.
+ * @param appConfig - The configuration object for the app
+ * @throws {Error} If initialization is currently in progress
+ * @example
+ * await init({ id: 'my-project-id' });
+ */
+export declare const init: (appConfig: AppConfig) => Promise<void>;
+/**
+ * Sends a custom event with the specified name and metadata.
+ * @param name - The name of the custom event.
+ * @param metadata - Optional metadata to attach to the event.
+ * @example
+ * // Send a custom event with metadata
+ * event('user_signup', { method: 'email', plan: 'premium' });
+ * @example
+ * // Send a custom event without metadata
+ * event('user_login');
+ * @remarks
+ * This function should be called after the app has been initialized using the `init` function.
+ */
+export declare const event: (name: string, metadata?: Record<string, MetadataType>) => void;
+/**
+ * Checks if the app has been initialized.
+ * @returns true if the app is initialized, false otherwise
+ */
+export declare const isInitialized: () => boolean;
+/**
+ * Gets the current initialization status for debugging purposes.
+ * @returns Object with detailed initialization state
+ */
+export declare const getInitializationStatus: () => {
+    isInitialized: boolean;
+    isInitializing: boolean;
+    hasInstance: boolean;
+};
+/**
+ * Destroys the current app instance and cleans up resources.
+ */
+export declare const destroy: () => void;

package/dist/esm/api.js

@@ -0,0 +1,183 @@
+import { App } from './app';
+import { debugLog } from './utils/logging';
+import { validateAndNormalizeConfig } from './utils/validations';
+import { INITIALIZATION_CONSTANTS } from './constants';
+import './types/window.types';
+export * as Types from './app.types';
+export * as Constants from './app.constants';
+let app = null;
+let isInitializing = false;
+/**
+ * Initializes the tracelog app with the provided configuration.
+ * If already initialized, this function returns early without error.
+ * @param appConfig - The configuration object for the app
+ * @throws {Error} If initialization is currently in progress
+ * @example
+ * await init({ id: 'my-project-id' });
+ */
+export const init = async (appConfig) => {
+    try {
+        debugLog.info('API', 'Library initialization started', { id: appConfig.id });
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            debugLog.clientError('API', 'Browser environment required - this library can only be used in a browser environment', {
+                hasWindow: typeof window !== 'undefined',
+                hasDocument: typeof document !== 'undefined',
+            });
+            throw new Error('This library can only be used in a browser environment');
+        }
+        if (app) {
+            debugLog.debug('API', 'Library already initialized, skipping duplicate initialization', {
+                projectId: appConfig.id,
+            });
+            return;
+        }
+        if (isInitializing) {
+            debugLog.debug('API', 'Concurrent initialization detected, waiting for completion', { projectId: appConfig.id });
+            let retries = 0;
+            const maxRetries = INITIALIZATION_CONSTANTS.MAX_CONCURRENT_RETRIES;
+            const retryDelay = INITIALIZATION_CONSTANTS.CONCURRENT_RETRY_DELAY_MS;
+            while (isInitializing && retries < maxRetries) {
+                await new Promise((resolve) => setTimeout(resolve, retryDelay));
+                retries++;
+            }
+            if (app) {
+                debugLog.debug('API', 'Concurrent initialization completed successfully', {
+                    projectId: appConfig.id,
+                    retriesUsed: retries,
+                });
+                return;
+            }
+            if (isInitializing) {
+                debugLog.error('API', 'Initialization timeout - concurrent initialization took too long', {
+                    projectId: appConfig.id,
+                    retriesUsed: retries,
+                    maxRetries,
+                });
+                throw new Error('App initialization timeout - concurrent initialization took too long');
+            }
+        }
+        isInitializing = true;
+        debugLog.debug('API', 'Validating and normalizing configuration', { projectId: appConfig.id });
+        const validatedConfig = validateAndNormalizeConfig(appConfig);
+        debugLog.debug('API', 'Creating App instance', { projectId: validatedConfig.id });
+        const instance = new App();
+        await instance.init(validatedConfig);
+        app = instance;
+        debugLog.info('API', 'Library initialization completed successfully', {
+            projectId: validatedConfig.id,
+        });
+    }
+    catch (error) {
+        // Ensure complete cleanup on initialization failure
+        if (app && !app.initialized) {
+            // Clean up partially initialized app instance
+            try {
+                app.destroy();
+            }
+            catch (cleanupError) {
+                debugLog.warn('API', 'Failed to cleanup partially initialized app', { cleanupError });
+            }
+        }
+        app = null;
+        debugLog.error('API', 'Initialization failed', { error });
+        throw error;
+    }
+    finally {
+        isInitializing = false;
+    }
+};
+/**
+ * Sends a custom event with the specified name and metadata.
+ * @param name - The name of the custom event.
+ * @param metadata - Optional metadata to attach to the event.
+ * @example
+ * // Send a custom event with metadata
+ * event('user_signup', { method: 'email', plan: 'premium' });
+ * @example
+ * // Send a custom event without metadata
+ * event('user_login');
+ * @remarks
+ * This function should be called after the app has been initialized using the `init` function.
+ */
+export const event = (name, metadata) => {
+    try {
+        if (!app) {
+            debugLog.clientError('API', 'Custom event failed - Library not initialized. Please call TraceLog.init() first', {
+                eventName: name,
+                hasMetadata: !!metadata,
+            });
+            throw new Error('App not initialized');
+        }
+        debugLog.debug('API', 'Sending custom event', {
+            eventName: name,
+            hasMetadata: !!metadata,
+            metadataKeys: metadata ? Object.keys(metadata) : [],
+        });
+        app.sendCustomEvent(name, metadata);
+    }
+    catch (error) {
+        debugLog.error('API', 'Event tracking failed', { eventName: name, error, hasMetadata: !!metadata });
+        if (error instanceof Error &&
+            (error.message === 'App not initialized' || error.message.includes('validation failed'))) {
+            throw error;
+        }
+    }
+};
+/**
+ * Checks if the app has been initialized.
+ * @returns true if the app is initialized, false otherwise
+ */
+export const isInitialized = () => {
+    return app !== null;
+};
+/**
+ * Gets the current initialization status for debugging purposes.
+ * @returns Object with detailed initialization state
+ */
+export const getInitializationStatus = () => {
+    return {
+        isInitialized: app !== null,
+        isInitializing: isInitializing,
+        hasInstance: app !== null,
+    };
+};
+/**
+ * Destroys the current app instance and cleans up resources.
+ */
+export const destroy = () => {
+    try {
+        debugLog.info('API', 'Library cleanup initiated');
+        if (!app) {
+            debugLog.warn('API', 'Cleanup called but Library was not initialized');
+            throw new Error('App not initialized');
+        }
+        app.destroy();
+        app = null;
+        isInitializing = false;
+        debugLog.info('API', 'Library cleanup completed successfully');
+    }
+    catch (error) {
+        debugLog.error('API', 'Cleanup failed', { error, hadApp: !!app, wasInitializing: isInitializing });
+    }
+};
+class TestBridge extends App {
+    isInitializing() {
+        return isInitializing;
+    }
+}
+// Auto-inject testing bridge only in development/testing environments
+if (process.env.NODE_ENV === 'dev') {
+    if (typeof window !== 'undefined') {
+        // Wait for DOM to be ready before injecting
+        const injectTestingBridge = () => {
+            window.__traceLogBridge = new TestBridge();
+        };
+        // Inject immediately if DOM is ready, otherwise wait
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', injectTestingBridge);
+        }
+        else {
+            injectTestingBridge();
+        }
+    }
+}

package/dist/esm/app.constants.d.ts

@@ -0,0 +1 @@
+export { DEFAULT_SESSION_TIMEOUT_MS } from './constants';

package/dist/esm/app.constants.js

@@ -0,0 +1 @@
+export { DEFAULT_SESSION_TIMEOUT_MS } from './constants';

package/dist/esm/app.d.ts

@@ -0,0 +1,59 @@
+import { EventManager } from './managers/event.manager';
+import { AppConfig } from './types/config.types';
+import { StateManager } from './managers/state.manager';
+import { SessionHandler } from './handlers/session.handler';
+import { PageViewHandler } from './handlers/page-view.handler';
+import { ClickHandler } from './handlers/click.handler';
+import { ScrollHandler } from './handlers/scroll.handler';
+import { GoogleAnalyticsIntegration } from './integrations/google-analytics.integration';
+import { StorageManager } from './managers/storage.manager';
+import { PerformanceHandler } from './handlers/performance.handler';
+import { ErrorHandler } from './handlers/error.handler';
+import { NetworkHandler } from './handlers/network.handler';
+export declare class App extends StateManager {
+    protected isInitialized: boolean;
+    protected googleAnalytics: GoogleAnalyticsIntegration | null;
+    protected storageManager: StorageManager;
+    protected eventManager: EventManager;
+    protected sessionHandler: SessionHandler;
+    protected pageViewHandler: PageViewHandler;
+    protected clickHandler: ClickHandler;
+    protected scrollHandler: ScrollHandler;
+    protected performanceHandler: PerformanceHandler;
+    protected errorHandler: ErrorHandler;
+    protected networkHandler: NetworkHandler;
+    protected suppressNextScrollTimer: number | null;
+    /**
+     * Returns the initialization status of the app
+     * @returns true if the app is fully initialized, false otherwise
+     */
+    get initialized(): boolean;
+    init(appConfig: AppConfig): Promise<void>;
+    /**
+     * Validates that the app is ready to initialize with the provided config
+     * This is a lightweight runtime validation layer that ensures the app receives proper config
+     * @param appConfig - The validated and normalized configuration
+     * @throws {ProjectIdValidationError} If project ID is invalid at runtime
+     */
+    private validateAppReadiness;
+    sendCustomEvent(name: string, metadata?: Record<string, unknown>): void;
+    destroy(): void;
+    private setState;
+    private setApiUrl;
+    private setConfig;
+    private setUserId;
+    private setDevice;
+    private setPageUrl;
+    private setIntegrations;
+    private initHandlers;
+    private initStorage;
+    private setEventManager;
+    private initSessionHandler;
+    private initPageViewHandler;
+    private onPageViewTrack;
+    private initClickHandler;
+    private initScrollHandler;
+    private initPerformanceHandler;
+    private initErrorHandler;
+    private initNetworkHandler;
+}