@levi123/trackers 4.0.0-dev.0

package/README.md

@@ -0,0 +1,220 @@
+# @levi123/trackers
+
+A high-performance tracking SDK with dual Web Worker architecture for optimal performance and scalability.
+
+## Features
+
+- **Dual Worker Architecture**: Separate workers for event processing and callback handling
+- **TypeScript Support**: Full TypeScript definitions and type safety
+- **Performance Optimized**: Non-blocking event processing using Web Workers
+- **Fault Tolerant**: Isolated workers prevent crashes from affecting the main thread
+- **Scalable**: Easy to extend with additional workers for specific event types
+- **Modern API**: Clean, intuitive API with callback support
+
+## Architecture
+
+```
+Page Event (click/load)
+    ↓
+Main Thread (tracking-sdk.js)
+    ↓ postMessage
+Event Worker (event-worker.js)
+    → Process logic → Calculate metrics
+    ↓ postMessage
+Callback Worker (callback-worker.js)
+    → Execute callbacks → API calls → Logging
+    ↓ postMessage (summaries)
+Main Thread
+    → User callbacks → Console/UI updates
+```
+
+## Installation
+
+```bash
+npm install @levi123/trackers
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { TrackingSDK } from '@levi123/trackers';
+
+// Initialize the SDK
+TrackingSDK.init({
+  apiEndpoint: 'https://your-analytics-server.com/track',
+  events: ['pageLoad', 'click', 'performance'],
+  workerTimeout: 5000,
+});
+
+// Register callbacks
+TrackingSDK.on('performanceResult', (data) => {
+  console.log('Performance metrics:', data.metrics);
+});
+
+TrackingSDK.on('clickTracked', (data) => {
+  console.log('Click tracked:', data.data);
+});
+
+TrackingSDK.on('error', (error) => {
+  console.error('Tracking error:', error);
+});
+
+// Track custom events
+TrackingSDK.trackEvent('customEvent', {
+  userId: '123',
+  action: 'button_click',
+  timestamp: Date.now(),
+});
+```
+
+### Advanced Configuration
+
+```typescript
+import { TrackingSDK, type TrackingConfig } from '@levi123/trackers';
+
+const config: TrackingConfig = {
+  apiEndpoint: 'https://analytics.example.com/track',
+  events: ['pageLoad', 'click', 'performance', 'scroll'],
+  workerTimeout: 10000,
+};
+
+TrackingSDK.init(config);
+
+// Get SDK status
+const status = TrackingSDK.getStatus();
+console.log('Worker status:', status.workerStatus);
+console.log('Registered callbacks:', status.registeredCallbacks);
+
+// Cleanup when done
+TrackingSDK.destroy();
+```
+
+### Callback Management
+
+```typescript
+// Register callback and get unsubscribe function
+const unsubscribe = TrackingSDK.on('pageLoad', (data) => {
+  console.log('Page loaded:', data.data);
+});
+
+// Unsubscribe when no longer needed
+unsubscribe();
+
+// Register multiple callbacks for the same event
+TrackingSDK.on('click', callback1);
+TrackingSDK.on('click', callback2);
+```
+
+## API Reference
+
+### TrackingSDK
+
+#### Methods
+
+- `init(config?: Partial<TrackingConfig>)` - Initialize the SDK
+- `trackEvent(eventName: string, data: EventData)` - Track a custom event
+- `on(eventType: string, callback: EventCallback)` - Register a callback
+- `getStatus()` - Get current SDK status
+- `destroy()` - Clean up and destroy the SDK
+
+#### Configuration
+
+```typescript
+interface TrackingConfig {
+  apiEndpoint: string;
+  events: string[];
+  workerTimeout: number;
+}
+```
+
+#### Event Data
+
+```typescript
+interface EventData {
+  timestamp: number;
+  [key: string]: any;
+}
+```
+
+#### Callback Data
+
+```typescript
+interface CallbackData {
+  type: string;
+  data: ProcessedEventData;
+  metrics?: PerformanceMetrics;
+  timestamp: number;
+  processingTime: number;
+  workerId: string;
+}
+```
+
+## Built-in Event Types
+
+- `pageLoad` - Page load events
+- `pageLoadComplete` - Complete page load with performance metrics
+- `userClick` - User click events
+- `performance` - Performance metrics
+- `performanceEntry` - Performance observer entries
+- `scroll` - Scroll events (throttled)
+
+## Worker Files
+
+The package includes three JavaScript files that need to be served from your public directory:
+
+- `event-worker.js` - Processes tracking events
+- `callback-worker.js` - Handles callbacks and communication
+- `tracking-sdk.js` - Main SDK file (for non-module usage)
+
+## Browser Support
+
+- Modern browsers with Web Worker support
+- ES6+ features required
+- TypeScript support for development
+
+## Performance Benefits
+
+1. **Non-blocking Processing**: Event processing happens in workers
+2. **Parallel Execution**: Event and callback workers run simultaneously
+3. **Fault Isolation**: Worker crashes don't affect the main thread
+4. **Scalable Architecture**: Easy to add more workers for specific tasks
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+```
+
+## License
+
+MIT
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+## Changelog
+
+### 0.0.0
+
+- Initial release
+- Dual worker architecture
+- TypeScript support
+- Basic event tracking
+- Performance monitoring

package/dist/esm/index.js

@@ -0,0 +1,402 @@
+"use client"
+class DebugTrackers {
+    constructor(enableLog) {
+        this.enableLog = !!enableLog;
+    }
+    log(message, ...args) {
+        this.enableLog && console.log(message, ...args);
+    }
+    warn(message, ...args) {
+        this.enableLog && console.warn(message, ...args);
+    }
+    error(message, ...args) {
+        this.enableLog && console.error(message, ...args);
+    }
+}
+const debugTrackers = new DebugTrackers();
+
+// ----- Enums -----
+var ITrackingEvent;
+(function (ITrackingEvent) {
+    ITrackingEvent["PAGE_LOAD"] = "pageLoad";
+    ITrackingEvent["CLICK"] = "click";
+    ITrackingEvent["PERFORMANCE"] = "performance";
+    ITrackingEvent["PERFORMANCE_ENTRY"] = "performanceEntry";
+    ITrackingEvent["SCROLL"] = "scroll";
+    ITrackingEvent["MANUAL_CLICK"] = "manualClick";
+})(ITrackingEvent || (ITrackingEvent = {}));
+
+class GXTrackingSDK {
+    constructor() {
+        this.config = {
+            events: [ITrackingEvent.PAGE_LOAD, ITrackingEvent.CLICK],
+            workerTimeout: 5000,
+        };
+        this.isInitialized = false;
+        this.eventWorker = null;
+        this.callbackWorker = null;
+        this.callbacks = {};
+        this.workerStatus = {
+            eventWorker: 'idle',
+            callbackWorker: 'idle',
+        };
+        this.perEventCallbacks = new Map();
+        // Private event handlers
+        this.handlePageLoad = () => {
+            this.trackEvent(ITrackingEvent.PAGE_LOAD, {
+                timestamp: Date.now(),
+                url: window.location.href,
+            });
+        };
+        this.handleClick = (e) => {
+            const target = e.target;
+            if (target.tagName !== 'SCRIPT' && target.tagName !== 'STYLE')
+                return;
+            this.trackEvent(ITrackingEvent.CLICK, {
+                target: target.tagName,
+                targetId: target.id || '',
+                targetClass: target.className || '',
+                x: e.clientX,
+                y: e.clientY,
+                timestamp: Date.now(),
+            });
+        };
+        if (typeof window !== 'undefined' && !window.Worker) {
+            debugTrackers.warn('Web Worker not supported. Falling back to main thread.');
+            return;
+        }
+    }
+    init(userConfig = {}) {
+        if (this.isInitialized) {
+            debugTrackers.warn('SDK already initialized');
+            return;
+        }
+        // Merge config
+        Object.assign(this.config, userConfig);
+        debugTrackers.log('🚀 GXTrackingSDK initialized with config:', this.config);
+        // Initialize workers
+        this.initWorkers();
+        const handleStartTracking = () => {
+            setTimeout(() => {
+                this.isInitialized = true;
+                this.startTracking();
+                debugTrackers.log('✅ All workers are running');
+            }, 0);
+        };
+        if (document.readyState === 'complete') {
+            handleStartTracking();
+        }
+        else {
+            window.addEventListener('load', handleStartTracking);
+        }
+    }
+    initWorkers() {
+        this.initEventWorker();
+        this.initCallbackWorker();
+    }
+    initEventWorker() {
+        try {
+            // Create Event Worker from package source (bundled by the app/bundler)
+            this.eventWorker = new Worker(new URL('./event-worker.ts', import.meta.url), {
+                type: 'module',
+            });
+            this.eventWorker.onmessage = (e) => {
+                const { type, data } = e.data;
+                this.workerStatus.eventWorker = 'active';
+                switch (type) {
+                    case 'processed':
+                        this.sendToCallbackWorker({
+                            type: 'processedResult',
+                            event: data.event,
+                            eventType: data.event,
+                            processedData: data.processedData,
+                            timestamp: Date.now(),
+                        });
+                        break;
+                    case 'error':
+                        this.handleError(data);
+                        break;
+                    default:
+                }
+            };
+            this.eventWorker.onerror = (error) => {
+                this.workerStatus.eventWorker = 'error';
+                this.handleError({ message: 'Event Worker crashed', error });
+            };
+            // Send initial config to Event Worker
+            this.sendToEventWorker({ type: 'init', config: this.config });
+            this.workerStatus.eventWorker = 'ready';
+        }
+        catch (error) {
+            this.handleError({ message: 'Failed to create Event Worker', error });
+        }
+    }
+    initCallbackWorker() {
+        try {
+            this.callbackWorker = new Worker(new URL('./callback-worker.ts', import.meta.url), {
+                type: 'module',
+            });
+            this.callbackWorker.onmessage = (e) => {
+                const { type, data } = e.data;
+                this.workerStatus.callbackWorker = 'active';
+                switch (type) {
+                    case 'executeCallbacks': {
+                        // Execute registered callbacks on main thread and send result back
+                        const { eventType, requestId, payload } = e.data || {};
+                        const callbacks = (eventType && this.callbacks[eventType]) || [];
+                        let successCount = 0;
+                        let errorCount = 0;
+                        const start = Date.now();
+                        const perEventId = (payload && payload.data && payload.data.eventId);
+                        const perEventCb = perEventId ? this.perEventCallbacks.get(perEventId) : undefined;
+                        if (perEventCb) {
+                            try {
+                                perEventCb(payload);
+                                successCount++;
+                            }
+                            catch (err) {
+                                errorCount++;
+                            }
+                            finally {
+                                this.perEventCallbacks.delete(perEventId);
+                            }
+                        }
+                        if (callbacks.length > 0) {
+                            callbacks.forEach((cb) => {
+                                try {
+                                    cb(payload);
+                                    successCount++;
+                                }
+                                catch (err) {
+                                    errorCount++;
+                                    // also forward error to error handlers if any
+                                    if (this.callbacks.error) {
+                                        this.callbacks.error.forEach((eCb) => {
+                                            try {
+                                                eCb({
+                                                    type: 'error',
+                                                    data: {
+                                                        message: 'Callback error',
+                                                        error: this.serializeError(err),
+                                                    },
+                                                    timestamp: Date.now(),
+                                                    processingTime: 0,
+                                                    workerId: 'tracking-sdk',
+                                                });
+                                            }
+                                            catch (_a) { }
+                                        });
+                                    }
+                                }
+                            });
+                        }
+                        const executionTime = Date.now() - start;
+                        // Respond to worker with results
+                        this.sendToCallbackWorker({
+                            type: 'executionResult',
+                            requestId,
+                            successCount,
+                            errorCount,
+                            executionTime,
+                        });
+                        break;
+                    }
+                    case 'callbackReady':
+                        debugTrackers.log('📨 Callback processed successfully');
+                        break;
+                    case 'error':
+                        this.handleError(data);
+                        break;
+                    default:
+                }
+            };
+            this.callbackWorker.onerror = (error) => {
+                this.workerStatus.callbackWorker = 'error';
+                this.handleError({ message: 'Callback Worker crashed', error });
+            };
+            // Send initial config to Callback Worker
+            this.sendToCallbackWorker({
+                type: 'init',
+                config: this.config,
+                callbacks: Object.keys(this.callbacks), // Inform about registered callbacks
+            });
+            this.workerStatus.callbackWorker = 'ready';
+        }
+        catch (error) {
+            this.handleError({ message: 'Failed to create Callback Worker', error });
+        }
+    }
+    startTracking() {
+        if (typeof window === 'undefined')
+            return;
+        debugTrackers.log('👁️ Starting event tracking...', this.config.events);
+        // Track page load events
+        if (this.config.events.includes(ITrackingEvent.PAGE_LOAD)) {
+            this.handlePageLoad();
+        }
+        // Track user clicks
+        this.config.events.includes(ITrackingEvent.CLICK) && document.addEventListener('click', this.handleClick);
+        // Track performance metrics
+        if (this.config.events.includes(ITrackingEvent.PERFORMANCE) && 'PerformanceObserver' in window) {
+            const observer = new PerformanceObserver((list) => {
+                list.getEntries().forEach((entry) => {
+                    this.trackEvent(ITrackingEvent.PERFORMANCE_ENTRY, {
+                        name: entry.name,
+                        entryType: entry.entryType,
+                        duration: Math.round(entry.duration),
+                        startTime: Math.round(entry.startTime),
+                        timestamp: Date.now(),
+                    });
+                });
+            });
+            observer.observe({
+                entryTypes: ['navigation', 'paint', 'resource', 'largest-contentful-paint'],
+            });
+        }
+        debugTrackers.log('✅ All event listeners attached');
+    }
+    trackEvent(eventName, data, callback) {
+        if (!this.isInitialized) {
+            debugTrackers.warn('SDK not initialized. Call init() first.');
+            return;
+        }
+        const eventId = data.eventId || `ev_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+        if (callback) {
+            this.perEventCallbacks.set(eventId, callback);
+        }
+        const eventData = {
+            type: 'track',
+            event: eventName,
+            data: Object.assign(Object.assign({}, data), { timestamp: Date.now(), eventId }),
+        };
+        debugTrackers.log('📤 Sending event to Event Worker:', eventName, eventData.data);
+        this.sendToEventWorker(eventData);
+    }
+    // Communication methods
+    sendToEventWorker(message) {
+        if (!this.eventWorker) {
+            debugTrackers.error('Event Worker not initialized');
+            return;
+        }
+        this.eventWorker.postMessage(message);
+    }
+    sendToCallbackWorker(message) {
+        if (!this.callbackWorker) {
+            debugTrackers.error('Callback Worker not initialized');
+            return;
+        }
+        this.callbackWorker.postMessage(message);
+    }
+    // Callback registration
+    on(eventType, callback) {
+        if (!this.callbacks[eventType]) {
+            this.callbacks[eventType] = [];
+        }
+        this.callbacks[eventType].push(callback);
+        debugTrackers.log(`🔗 Registered callback for "${eventType}". Total: ${this.callbacks[eventType].length}`);
+        // Notify Callback Worker about new callback
+        this.sendToCallbackWorker({
+            type: 'registerCallback',
+            eventType: eventType,
+            callbackCount: this.callbacks[eventType].length,
+        });
+        return () => {
+            // Return unsubscribe function
+            if (!this.callbacks[eventType])
+                return;
+            const index = this.callbacks[eventType].indexOf(callback);
+            if (index > -1) {
+                this.callbacks[eventType].splice(index, 1);
+                debugTrackers.log(`❌ Unregistered callback for "${eventType}"`);
+            }
+        };
+    }
+    // Error handling
+    handleError(errorData) {
+        const serialized = this.serializeError(errorData);
+        if (this.callbacks.error) {
+            this.callbacks.error.forEach((cb) => cb(serialized));
+        }
+        this.sendToCallbackWorker({
+            type: 'error',
+            data: serialized,
+            timestamp: Date.now(),
+        });
+    }
+    serializeError(input) {
+        try {
+            if (!input)
+                return { message: 'Unknown error' };
+            if (input instanceof Error) {
+                return { message: input.message, name: input.name, stack: input.stack };
+            }
+            if (typeof input === 'string')
+                return { message: input };
+            if (input.message || input.error) {
+                const err = input.error;
+                const base = {
+                    message: input.message || 'Error',
+                    context: undefined,
+                };
+                if (err instanceof Error) {
+                    return Object.assign(Object.assign({}, base), { error: { message: err.message, name: err.name, stack: err.stack } });
+                }
+                try {
+                    return Object.assign(Object.assign({}, base), { error: JSON.parse(JSON.stringify(err)) });
+                }
+                catch (_a) {
+                    return Object.assign(Object.assign({}, base), { error: String(err) });
+                }
+            }
+            return JSON.parse(JSON.stringify(input));
+        }
+        catch (_b) {
+            return { message: 'Unserializable error' };
+        }
+    }
+    // Health check
+    getStatus() {
+        return {
+            isInitialized: this.isInitialized,
+            workerStatus: this.workerStatus,
+            registeredCallbacks: Object.keys(this.callbacks),
+            totalCallbacks: Object.values(this.callbacks).reduce((sum, cbs) => sum + cbs.length, 0),
+        };
+    }
+    // Cleanup
+    destroy() {
+        debugTrackers.log('🧹 Destroying GXTrackingSDK...');
+        // Remove event listeners
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('load', this.handlePageLoad);
+            document.removeEventListener('click', this.handleClick);
+        }
+        // Terminate workers
+        if (this.eventWorker) {
+            this.eventWorker.terminate();
+            this.eventWorker = null;
+            debugTrackers.log('🔌 Event Worker terminated');
+        }
+        if (this.callbackWorker) {
+            this.callbackWorker.terminate();
+            this.callbackWorker = null;
+            debugTrackers.log('🔌 Callback Worker terminated');
+        }
+        // Clear callbacks
+        this.callbacks = {};
+        this.isInitialized = false;
+        this.workerStatus = {
+            eventWorker: 'destroyed',
+            callbackWorker: 'destroyed',
+        };
+        debugTrackers.log('✅ GXTrackingSDK destroyed successfully');
+    }
+}
+// Create and expose the SDK instance
+const gxTrackingSDK = new GXTrackingSDK();
+// Make it available globally
+if (typeof window !== 'undefined') {
+    window.GXTrackingSDK = gxTrackingSDK;
+}
+
+export { ITrackingEvent, gxTrackingSDK };