iframe-tracking-sdk 1.0.0

package/dist/db.d.ts

@@ -0,0 +1,47 @@
+import { TrackingEvent, EventStatus } from './types';
+export declare class EventQueueDB {
+    private dbName;
+    private storeName;
+    private dbVersion;
+    private maxQueueSize;
+    private debug;
+    constructor(maxQueueSize?: number, debug?: boolean);
+    private isBrowser;
+    private getDB;
+    /**
+     * Enqueue an event. Performs FIFO cleaning if the size exceeds maxQueueSize.
+     */
+    enqueue(event: TrackingEvent): Promise<void>;
+    /**
+     * Enforce FIFO queue limit. If database has more than maxQueueSize items, delete oldest 50.
+     */
+    private enforceLimit;
+    /**
+     * Fetch pending events up to limit.
+     */
+    getPendingEvents(limit?: number): Promise<TrackingEvent[]>;
+    /**
+     * Update status of multiple events.
+     */
+    updateStatus(eventIds: string[], status: EventStatus, errorMessage?: string): Promise<void>;
+    /**
+     * Delete successfully synced events.
+     */
+    deleteDone(eventIds: string[]): Promise<void>;
+    /**
+     * Reset events stuck in 'syncing' status back to 'pending'.
+     */
+    resetSyncingToPending(): Promise<void>;
+    /**
+     * Delete old dead_letter events (older than daysLimit).
+     */
+    cleanupOldDeadLetters(daysLimit?: number): Promise<number>;
+    /**
+     * Get all events in the store for UI rendering/debugging.
+     */
+    getAllEvents(limit?: number): Promise<TrackingEvent[]>;
+    /**
+     * Clear all events in the store.
+     */
+    clear(): Promise<void>;
+}

package/dist/db.js

@@ -0,0 +1,290 @@
+export class EventQueueDB {
+    dbName = 'IframeTrackingDB';
+    storeName = 'events';
+    dbVersion = 1;
+    maxQueueSize;
+    debug;
+    constructor(maxQueueSize = 500, debug = false) {
+        this.maxQueueSize = maxQueueSize;
+        this.debug = debug;
+    }
+    isBrowser() {
+        return typeof window !== 'undefined';
+    }
+    getDB() {
+        return new Promise((resolve, reject) => {
+            if (!this.isBrowser()) {
+                reject(new Error('IndexedDB is only available in the browser'));
+                return;
+            }
+            const request = indexedDB.open(this.dbName, this.dbVersion);
+            request.onerror = () => {
+                if (this.debug)
+                    console.error('[Tracking DB] Failed to open IndexedDB');
+                reject(request.error);
+            };
+            request.onsuccess = () => {
+                resolve(request.result);
+            };
+            request.onupgradeneeded = (event) => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains(this.storeName)) {
+                    const store = db.createObjectStore(this.storeName, { keyPath: 'event_id' });
+                    store.createIndex('status', 'status', { unique: false });
+                    store.createIndex('created_at', 'created_at', { unique: false });
+                    if (this.debug)
+                        console.log('[Tracking DB] Object store created');
+                }
+            };
+        });
+    }
+    /**
+     * Enqueue an event. Performs FIFO cleaning if the size exceeds maxQueueSize.
+     */
+    async enqueue(event) {
+        const db = await this.getDB();
+        // First, check the size and enforce FIFO limit
+        await this.enforceLimit(db);
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, 'readwrite');
+            const store = transaction.objectStore(this.storeName);
+            const request = store.put(event);
+            request.onsuccess = () => {
+                if (this.debug)
+                    console.log(`[Tracking DB] Enqueued event ${event.event_id} (${event.event_name})`);
+                resolve();
+            };
+            request.onerror = () => {
+                if (this.debug)
+                    console.error('[Tracking DB] Enqueue failed', request.error);
+                reject(request.error);
+            };
+        });
+    }
+    /**
+     * Enforce FIFO queue limit. If database has more than maxQueueSize items, delete oldest 50.
+     */
+    async enforceLimit(db) {
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, 'readwrite');
+            const store = transaction.objectStore(this.storeName);
+            const countRequest = store.count();
+            countRequest.onsuccess = () => {
+                const count = countRequest.result;
+                if (count < this.maxQueueSize) {
+                    resolve();
+                    return;
+                }
+                if (this.debug)
+                    console.warn(`[Tracking DB] Queue full (${count}/${this.maxQueueSize}). Removing oldest 50 events.`);
+                // Find and delete oldest 50 events using the created_at index
+                const createdAtIndex = store.index('created_at');
+                const cursorRequest = createdAtIndex.openCursor(null, 'next'); // oldest first
+                let deletedCount = 0;
+                cursorRequest.onsuccess = () => {
+                    const cursor = cursorRequest.result;
+                    if (cursor && deletedCount < 50) {
+                        cursor.delete();
+                        deletedCount++;
+                        cursor.continue();
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+                cursorRequest.onerror = () => reject(cursorRequest.error);
+            };
+            countRequest.onerror = () => reject(countRequest.error);
+        });
+    }
+    /**
+     * Fetch pending events up to limit.
+     */
+    async getPendingEvents(limit = 50) {
+        const db = await this.getDB();
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, 'readonly');
+            const store = transaction.objectStore(this.storeName);
+            const statusIndex = store.index('status');
+            const events = [];
+            const request = statusIndex.openCursor(IDBKeyRange.only('pending'));
+            request.onsuccess = () => {
+                const cursor = request.result;
+                if (cursor && events.length < limit) {
+                    events.push(cursor.value);
+                    cursor.continue();
+                }
+                else {
+                    resolve(events);
+                }
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Update status of multiple events.
+     */
+    async updateStatus(eventIds, status, errorMessage) {
+        if (eventIds.length === 0)
+            return;
+        const db = await this.getDB();
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, 'readwrite');
+            const store = transaction.objectStore(this.storeName);
+            // Use real Promise.all to avoid manual counter race condition
+            const ops = eventIds.map(id => new Promise((res, rej) => {
+                const getReq = store.get(id);
+                getReq.onsuccess = () => {
+                    const event = getReq.result;
+                    if (!event) {
+                        res();
+                        return;
+                    }
+                    event.status = status;
+                    if (status === 'failed') {
+                        event.retry_count++;
+                    }
+                    if (errorMessage) {
+                        event.error_message = errorMessage;
+                    }
+                    const putReq = store.put(event);
+                    putReq.onsuccess = () => res();
+                    putReq.onerror = () => rej(putReq.error);
+                };
+                getReq.onerror = () => rej(getReq.error);
+            }));
+            Promise.all(ops).then(() => resolve()).catch(reject);
+        });
+    }
+    /**
+     * Delete successfully synced events.
+     */
+    async deleteDone(eventIds) {
+        if (eventIds.length === 0)
+            return;
+        const db = await this.getDB();
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, 'readwrite');
+            const store = transaction.objectStore(this.storeName);
+            let completedCount = 0;
+            eventIds.forEach((id) => {
+                const request = store.delete(id);
+                request.onsuccess = () => {
+                    completedCount++;
+                    if (completedCount === eventIds.length) {
+                        resolve();
+                    }
+                };
+                request.onerror = () => reject(request.error);
+            });
+        });
+    }
+    /**
+     * Reset events stuck in 'syncing' status back to 'pending'.
+     */
+    async resetSyncingToPending() {
+        const db = await this.getDB();
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, 'readwrite');
+            const store = transaction.objectStore(this.storeName);
+            const statusIndex = store.index('status');
+            const request = statusIndex.openCursor(IDBKeyRange.only('syncing'));
+            const updates = [];
+            request.onsuccess = () => {
+                const cursor = request.result;
+                if (cursor) {
+                    const event = cursor.value;
+                    event.status = 'pending';
+                    const updatePromise = new Promise((res, rej) => {
+                        const putReq = store.put(event);
+                        putReq.onsuccess = () => res();
+                        putReq.onerror = () => rej(putReq.error);
+                    });
+                    updates.push(updatePromise);
+                    cursor.continue();
+                }
+                else {
+                    Promise.all(updates).then(() => resolve()).catch(reject);
+                }
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Delete old dead_letter events (older than daysLimit).
+     */
+    async cleanupOldDeadLetters(daysLimit = 7) {
+        const db = await this.getDB();
+        const cutOffTime = Date.now() - (daysLimit * 24 * 60 * 60 * 1000);
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, 'readwrite');
+            const store = transaction.objectStore(this.storeName);
+            const statusIndex = store.index('status');
+            let deletedCount = 0;
+            const request = statusIndex.openCursor(IDBKeyRange.only('dead_letter'));
+            request.onsuccess = () => {
+                const cursor = request.result;
+                if (cursor) {
+                    const event = cursor.value;
+                    if (event.created_at < cutOffTime) {
+                        cursor.delete();
+                        deletedCount++;
+                    }
+                    cursor.continue();
+                }
+                else {
+                    if (this.debug && deletedCount > 0) {
+                        console.log(`[Tracking DB] Cleaned up ${deletedCount} dead-letter events older than ${daysLimit} days.`);
+                    }
+                    resolve(deletedCount);
+                }
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Get all events in the store for UI rendering/debugging.
+     */
+    async getAllEvents(limit = 100) {
+        const db = await this.getDB();
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, 'readonly');
+            const store = transaction.objectStore(this.storeName);
+            const createdAtIndex = store.index('created_at');
+            const events = [];
+            const request = createdAtIndex.openCursor(null, 'prev'); // newest first
+            request.onsuccess = () => {
+                const cursor = request.result;
+                if (cursor && events.length < limit) {
+                    events.push(cursor.value);
+                    cursor.continue();
+                }
+                else {
+                    resolve(events);
+                }
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    /**
+     * Clear all events in the store.
+     */
+    async clear() {
+        const db = await this.getDB();
+        return new Promise((resolve, reject) => {
+            const transaction = db.transaction(this.storeName, 'readwrite');
+            const store = transaction.objectStore(this.storeName);
+            const request = store.clear();
+            request.onsuccess = () => {
+                if (this.debug)
+                    console.log('[Tracking DB] Database queue cleared.');
+                resolve();
+            };
+            request.onerror = () => {
+                if (this.debug)
+                    console.error('[Tracking DB] Clear failed', request.error);
+                reject(request.error);
+            };
+        });
+    }
+}

package/dist/host.d.ts

@@ -0,0 +1,49 @@
+import { EventQueueDB } from './db';
+import { IframeHostTrackerConfig } from './types';
+export declare class IframeHostTracker {
+    private config;
+    private db;
+    private syncService;
+    private activeNonce;
+    private isHandshakeComplete;
+    private debug;
+    private immediateSyncEvents;
+    constructor(config: IframeHostTrackerConfig);
+    private isBrowser;
+    /**
+     * Initialize the tracking host. Registers event listeners and starts the sync engine.
+     */
+    start(): void;
+    /**
+     * Stop the tracking host. Cleans up event listeners and stops the sync engine.
+     */
+    stop(): void;
+    /**
+     * Force an immediate sync of any pending events.
+     */
+    flush(): Promise<void>;
+    /**
+     * Update optional local credentials.
+     * sessionId is kept only for backward-compatible local debugging and is not sent to the API.
+     */
+    updateCredentials(sessionId: string, hmacSecret: string): void;
+    /**
+     * Get the underlying database instance for advanced debugging/querying.
+     */
+    getDB(): EventQueueDB;
+    /**
+     * Initiate a secure Handshake with the target iframe (Deprecated / Handshake disabled).
+     */
+    initiateHandshake(iframeWindow: Window): string;
+    private getIframeOrigin;
+    private handleMessage;
+    private handleLearningEvent;
+    /**
+     * Filter out parameters used for envelope/signature routing to keep db/payload clean.
+     */
+    private cleanPayload;
+    /**
+     * Clear all events in the local durable queue.
+     */
+    clearQueue(): Promise<void>;
+}

package/dist/host.js

@@ -0,0 +1,215 @@
+import { EventQueueDB } from './db';
+import { SyncService } from './sync';
+export class IframeHostTracker {
+    config;
+    db;
+    syncService;
+    activeNonce = null;
+    isHandshakeComplete = true;
+    debug;
+    // Events that trigger immediate batch upload to Backend
+    immediateSyncEvents = new Set([
+        'session_end',
+        'course_finish',
+        'unit_finish',
+        'unit_submit',
+        'unit_restart'
+    ]);
+    constructor(config) {
+        this.config = config;
+        this.debug = config.debug || false;
+        this.db = new EventQueueDB(config.maxQueueSize || 500, this.debug);
+        this.syncService = new SyncService(this.db, {
+            apiEndpoint: config.apiEndpoint,
+            getJwtToken: config.getJwtToken,
+            onRefreshToken: config.onRefreshToken,
+            batchIntervalMs: config.batchIntervalMs,
+            maxRetryCount: config.maxRetryCount,
+            onSyncStatusChange: config.onSyncStatusChange,
+            onEventSynced: config.onEventSynced,
+            onDeadLetter: config.onDeadLetter,
+            debug: this.debug
+        });
+    }
+    isBrowser() {
+        return typeof window !== 'undefined';
+    }
+    /**
+     * Initialize the tracking host. Registers event listeners and starts the sync engine.
+     */
+    start() {
+        if (!this.isBrowser())
+            return;
+        // Start postMessage listener
+        window.addEventListener('message', this.handleMessage);
+        // Start sync service (periodic batches)
+        this.syncService.start();
+        // Clean up dead-letters older than 7 days once on startup
+        this.db.cleanupOldDeadLetters(7).catch((err) => {
+            if (this.debug)
+                console.error('[Tracking Host] Dead-letter cleanup error:', err);
+        });
+        if (this.debug)
+            console.log('[Tracking Host] Initialized and listening for messages.');
+    }
+    /**
+     * Stop the tracking host. Cleans up event listeners and stops the sync engine.
+     */
+    stop() {
+        if (!this.isBrowser())
+            return;
+        window.removeEventListener('message', this.handleMessage);
+        this.syncService.stop();
+        this.activeNonce = null;
+        this.isHandshakeComplete = false;
+        if (this.debug)
+            console.log('[Tracking Host] Stopped.');
+    }
+    /**
+     * Force an immediate sync of any pending events.
+     */
+    async flush() {
+        await this.syncService.syncNow(true);
+    }
+    /**
+     * Update optional local credentials.
+     * sessionId is kept only for backward-compatible local debugging and is not sent to the API.
+     */
+    updateCredentials(sessionId, hmacSecret) {
+        this.config.sessionId = sessionId;
+        this.config.hmacSecret = hmacSecret;
+        if (this.debug) {
+            console.log(`[Tracking Host] Credentials updated → sessionId: ${sessionId}`);
+        }
+    }
+    /**
+     * Get the underlying database instance for advanced debugging/querying.
+     */
+    getDB() {
+        return this.db;
+    }
+    /**
+     * Initiate a secure Handshake with the target iframe (Deprecated / Handshake disabled).
+     */
+    initiateHandshake(iframeWindow) {
+        this.isHandshakeComplete = true;
+        if (this.debug) {
+            console.log('[Tracking Host] Handshake is disabled. Client ready.');
+        }
+        return '';
+    }
+    getIframeOrigin() {
+        try {
+            const url = new URL(this.config.iframeUrl);
+            return url.origin;
+        }
+        catch (e) {
+            // Fallback if URL parsing fails
+            if (this.config.trustedOrigins.length > 0) {
+                return this.config.trustedOrigins[0];
+            }
+            return '*';
+        }
+    }
+    handleMessage = async (event) => {
+        // 1. Strict Origin Validation (Bypassed / Warning only)
+        if (this.debug && !this.config.trustedOrigins.includes(event.origin)) {
+            console.warn(`[Tracking Host] Received postMessage from untrusted origin: ${event.origin}. Proceeding anyway.`);
+        }
+        // 2. Safe Parsing & XSS Prevention
+        let rawData;
+        try {
+            rawData = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+        }
+        catch (e) {
+            if (this.debug)
+                console.warn('[Security] Failed to parse message payload. Dropping.', event.data);
+            return;
+        }
+        if (!rawData || typeof rawData !== 'object')
+            return;
+        // 3. Handle Learning Event
+        if (rawData.type === 'LEARNING_EVENT') {
+            await this.handleLearningEvent(rawData);
+        }
+    };
+    async handleLearningEvent(message) {
+        // Schema Validation
+        const payload = message.payload;
+        if (!payload || typeof payload !== 'object' || !payload.event_name) {
+            if (this.debug)
+                console.error('[Tracking Host] Malformed event payload. Missing event_name.', message);
+            return;
+        }
+        // Generate Event ID theo chuẩn: evt_[timestamp_ms]_[random_string_8_chars]
+        const randomChars = Math.random().toString(36).substring(2, 10);
+        const eventId = `evt_${Date.now()}_${randomChars}`;
+        const enrichedPayload = {
+            ...this.cleanPayload(payload),
+        };
+        if (this.config.sectionId) {
+            enrichedPayload.section_id = this.config.sectionId;
+        }
+        // Notify the host app when a restart-like event is detected.
+        // The backend treats unit_restart as a new attempt without requiring session_id.
+        const isSessionResetEvent = payload.event_name === 'unit_restart' ||
+            (payload.event_name === 'unit_start' && (payload.game === 'find_the_words' || payload.question_type === 'find_the_words'));
+        if (isSessionResetEvent && this.config.onSessionRefreshNeeded) {
+            if (this.debug) {
+                console.log(`[Tracking Host] Restart-like event '${payload.event_name}' detected. Notifying host app.`);
+            }
+            this.config.onSessionRefreshNeeded(payload.event_name);
+        }
+        // Data Enrichment
+        const enrichedEvent = {
+            event_id: eventId,
+            user_id: this.config.userId,
+            app_id: this.config.appId,
+            event_name: payload.event_name,
+            payload: enrichedPayload,
+            signature: message.signature || '',
+            timestamp: message.timestamp || Date.now(),
+            client_timestamp: Date.now(),
+            status: 'pending',
+            retry_count: 0,
+            created_at: Date.now()
+        };
+        if (this.config.sessionId) {
+            enrichedEvent.session_id = this.config.sessionId;
+        }
+        // 5. Store Event in Durable Queue (IndexedDB)
+        try {
+            await this.db.enqueue(enrichedEvent);
+            // Fire onEventReceived callback
+            this.config.onEventReceived?.(enrichedEvent);
+            // 6. Trigger Sync Immediately for Critical Events
+            const shouldSyncImmediately = this.immediateSyncEvents.has(payload.event_name);
+            if (shouldSyncImmediately) {
+                if (this.debug)
+                    console.log(`[Tracking Host] Critical event '${payload.event_name}' triggered immediate sync.`);
+                // Run sync on next event loop tick so db transaction can settle
+                setTimeout(() => this.syncService.syncNow(), 0);
+            }
+        }
+        catch (err) {
+            if (this.debug)
+                console.error('[Tracking Host] Failed to save tracking event to queue:', err);
+        }
+    }
+    /**
+     * Filter out parameters used for envelope/signature routing to keep db/payload clean.
+     */
+    cleanPayload(payload) {
+        const { event_name, event_id, ...rest } = payload;
+        return {
+            event_name,
+            ...rest
+        };
+    }
+    /**
+     * Clear all events in the local durable queue.
+     */
+    async clearQueue() {
+        await this.db.clear();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types';
+export { EventQueueDB } from './db';
+export { SyncService } from './sync';
+export { IframeHostTracker } from './host';
+export { IframeClientTracker } from './client';
+export { useIframeHostTracking } from './react-hook';
+export type { UseIframeHostTrackingResult } from './react-hook';
+export { generateNonce, sortObjectKeys, buildCanonicalString, signHmacSha256, verifyHmacSha256 } from './security';
+export { EventProcessor } from './processor';
+export type { EventCategory, BatchRequestBody } from './processor';

package/dist/index.js

@@ -0,0 +1,16 @@
+// Export Types
+export * from './types';
+// Export Database Queue
+export { EventQueueDB } from './db';
+// Export Sync Engine
+export { SyncService } from './sync';
+// Export Host tracker
+export { IframeHostTracker } from './host';
+// Export Client tracker
+export { IframeClientTracker } from './client';
+// Export React Hook for Next.js
+export { useIframeHostTracking } from './react-hook';
+// Export Cryptographic Security Utilities
+export { generateNonce, sortObjectKeys, buildCanonicalString, signHmacSha256, verifyHmacSha256 } from './security';
+// Export Event Processor (browser-independent, usable in Node.js/NestJS backends)
+export { EventProcessor } from './processor';