iframe-tracking-sdk 1.0.0

package/dist/sync.d.ts

@@ -0,0 +1,53 @@
+import { EventQueueDB } from './db';
+import { TrackingEvent } from './types';
+export declare class SyncService {
+    private db;
+    private apiEndpoint;
+    private getJwtToken;
+    private onRefreshToken?;
+    private batchIntervalMs;
+    private maxRetryCount;
+    private onSyncStatusChange?;
+    private onEventSynced?;
+    private onDeadLetter?;
+    private debug;
+    private periodicTimer;
+    private isSyncing;
+    private backoffIndex;
+    private backoffDelays;
+    private backoffTimeout;
+    constructor(db: EventQueueDB, config: {
+        apiEndpoint: string;
+        getJwtToken: () => Promise<string> | string;
+        onRefreshToken?: () => Promise<boolean | string>;
+        batchIntervalMs?: number;
+        maxRetryCount?: number;
+        onSyncStatusChange?: (status: 'idle' | 'syncing' | 'error') => void;
+        onEventSynced?: (eventIds: string[]) => void;
+        onDeadLetter?: (event: TrackingEvent) => void;
+        debug?: boolean;
+    });
+    private isBrowser;
+    /**
+     * Start periodic batch syncing and register connectivity listeners.
+     */
+    start(): void;
+    /**
+     * Stop periodic syncing and clean up event listeners.
+     */
+    stop(): void;
+    private handleOnline;
+    private handleOffline;
+    private handleVisibilityChange;
+    private handleBeforeUnload;
+    /**
+     * Trigger the sync engine manually.
+     */
+    syncNow(force?: boolean): Promise<void>;
+    private runSyncProcess;
+    private sendBatchWithTimeout;
+    private handleResponse;
+    private handlePermanentFailure;
+    private handleTemporaryFailure;
+    private scheduleBackoff;
+}

package/dist/sync.js

@@ -0,0 +1,336 @@
+export class SyncService {
+    db;
+    apiEndpoint;
+    getJwtToken;
+    onRefreshToken;
+    batchIntervalMs;
+    maxRetryCount;
+    onSyncStatusChange;
+    onEventSynced;
+    onDeadLetter;
+    debug;
+    periodicTimer = null;
+    isSyncing = false;
+    backoffIndex = 0;
+    backoffDelays = [30000, 60000, 120000, 300000, 600000]; // 30s, 60s, 2m, 5m, 10m
+    backoffTimeout = null;
+    constructor(db, config) {
+        this.db = db;
+        this.apiEndpoint = config.apiEndpoint;
+        this.getJwtToken = config.getJwtToken;
+        this.onRefreshToken = config.onRefreshToken;
+        this.batchIntervalMs = config.batchIntervalMs || 30000;
+        this.maxRetryCount = config.maxRetryCount || 5;
+        this.onSyncStatusChange = config.onSyncStatusChange;
+        this.onEventSynced = config.onEventSynced;
+        this.onDeadLetter = config.onDeadLetter;
+        this.debug = config.debug || false;
+    }
+    isBrowser() {
+        return typeof window !== 'undefined';
+    }
+    /**
+     * Start periodic batch syncing and register connectivity listeners.
+     */
+    start() {
+        if (!this.isBrowser())
+            return;
+        this.stop();
+        // Reset syncing state for events that got stuck due to a previous crash
+        this.db.resetSyncingToPending()
+            .then(() => this.syncNow())
+            .catch((err) => {
+            if (this.debug)
+                console.error('[Tracking Sync] Failed to reset syncing state:', err);
+        });
+        // Schedule regular syncs
+        this.periodicTimer = setInterval(() => {
+            this.syncNow();
+        }, this.batchIntervalMs);
+        // Online/Offline listeners
+        window.addEventListener('online', this.handleOnline);
+        window.addEventListener('offline', this.handleOffline);
+        // Document Visibility / Unload triggers
+        window.addEventListener('visibilitychange', this.handleVisibilityChange);
+        window.addEventListener('beforeunload', this.handleBeforeUnload);
+        if (this.debug)
+            console.log('[Tracking Sync] Service started');
+    }
+    /**
+     * Stop periodic syncing and clean up event listeners.
+     */
+    stop() {
+        if (this.periodicTimer) {
+            clearInterval(this.periodicTimer);
+            this.periodicTimer = null;
+        }
+        if (this.backoffTimeout) {
+            clearTimeout(this.backoffTimeout);
+            this.backoffTimeout = null;
+        }
+        if (this.isBrowser()) {
+            window.removeEventListener('online', this.handleOnline);
+            window.removeEventListener('offline', this.handleOffline);
+            window.removeEventListener('visibilitychange', this.handleVisibilityChange);
+            window.removeEventListener('beforeunload', this.handleBeforeUnload);
+        }
+        if (this.debug)
+            console.log('[Tracking Sync] Service stopped');
+    }
+    handleOnline = () => {
+        if (this.debug)
+            console.log('[Tracking Sync] Browser is online. Triggering immediate sync.');
+        this.backoffIndex = 0; // Reset backoff when network restores
+        this.syncNow();
+    };
+    handleOffline = () => {
+        if (this.debug)
+            console.warn('[Tracking Sync] Browser is offline. Sync suspended.');
+    };
+    handleVisibilityChange = () => {
+        if (typeof document !== 'undefined' && document.visibilityState === 'hidden') {
+            if (this.debug)
+                console.log('[Tracking Sync] App visibility hidden. Flushing queue.');
+            this.syncNow(true); // Sync immediately when user switches tabs
+        }
+    };
+    handleBeforeUnload = () => {
+        if (this.debug)
+            console.log('[Tracking Sync] Page unloading. Final queue flush.');
+        this.syncNow(true); // Synchronous send-beacon-like sync during page exit
+    };
+    /**
+     * Trigger the sync engine manually.
+     */
+    async syncNow(force = false) {
+        if (this.isSyncing)
+            return;
+        if (this.isBrowser() && !navigator.onLine && !force) {
+            if (this.debug)
+                console.log('[Tracking Sync] Offline. Skipping sync.');
+            return;
+        }
+        this.isSyncing = true;
+        this.onSyncStatusChange?.('syncing');
+        try {
+            await this.runSyncProcess();
+            this.onSyncStatusChange?.('idle');
+        }
+        catch (error) {
+            if (this.debug)
+                console.error('[Tracking Sync] Sync error occurred:', error);
+            this.onSyncStatusChange?.('error');
+            this.scheduleBackoff();
+        }
+        finally {
+            this.isSyncing = false;
+        }
+    }
+    async runSyncProcess() {
+        // 1. Fetch pending events (up to 50 at a time)
+        const events = await this.db.getPendingEvents(50);
+        if (events.length === 0) {
+            return;
+        }
+        if (this.debug)
+            console.log(`[Tracking Sync] Syncing batch of ${events.length} events...`);
+        // 2. Mark events as syncing
+        const eventIds = events.map(e => e.event_id);
+        await this.db.updateStatus(eventIds, 'syncing');
+        let jwtToken = '';
+        try {
+            jwtToken = (await this.getJwtToken()) || '';
+        }
+        catch (err) {
+            if (this.debug)
+                console.warn('[Tracking Sync] Failed to retrieve JWT token, proceeding with empty token:', err);
+        }
+        // 3. Make HTTP request with 15s timeout
+        try {
+            const response = await this.sendBatchWithTimeout(events, jwtToken, 15000);
+            await this.handleResponse(response, events, jwtToken);
+        }
+        catch (error) {
+            // Revert status to pending and let retry handlers manage
+            await this.db.updateStatus(eventIds, 'pending');
+            throw error;
+        }
+    }
+    async sendBatchWithTimeout(events, jwtToken, timeoutMs) {
+        const controller = new AbortController();
+        const id = setTimeout(() => controller.abort(), timeoutMs);
+        const body = {
+            user_id: events[0].user_id,
+            app_id: events[0].app_id,
+            app_version: '1.0.0',
+            section_id: events.find(e => e.payload && e.payload.section_id)?.payload.section_id || '',
+            events: events.map(e => {
+                // Extract event_name from payload, spread remaining fields flat (no double-spread)
+                // session_id is intentionally excluded from the API payload (local debug only)
+                const { event_name, ...payloadRest } = e.payload;
+                return {
+                    event_id: e.event_id,
+                    event_name: e.event_name,
+                    timestamp: e.timestamp,
+                    client_timestamp: e.client_timestamp,
+                    ...payloadRest // flat spread: word_id, score, is_correct, etc.
+                };
+            })
+        };
+        try {
+            const response = await fetch(this.apiEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${jwtToken}`,
+                    'X-App-Version': '1.0.0'
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal
+            });
+            clearTimeout(id);
+            return response;
+        }
+        catch (err) {
+            clearTimeout(id);
+            throw err;
+        }
+    }
+    async handleResponse(response, events, currentToken, isRetry = false) {
+        const eventIds = events.map(e => e.event_id);
+        // -- Status 200 OK: Batch Sync Succeeded (Handle Partial successes) --
+        if (response.ok) {
+            const result = await response.json();
+            this.backoffIndex = 0; // Reset backoff upon successful communication
+            if (result.rejected_details && result.rejected_details.length > 0) {
+                const rejectedMap = new Map();
+                result.rejected_details.forEach(item => {
+                    rejectedMap.set(item.event_id, item.reason);
+                });
+                const acceptedIds = [];
+                const rejectedIds = [];
+                events.forEach(event => {
+                    if (rejectedMap.has(event.event_id)) {
+                        rejectedIds.push(event.event_id);
+                        // Fire callback
+                        this.handlePermanentFailure(event, rejectedMap.get(event.event_id) || 'REJECTED_BY_SERVER');
+                    }
+                    else {
+                        acceptedIds.push(event.event_id);
+                    }
+                });
+                // Delete successful/duplicate ones, route rejected ones to failed/dead_letter
+                await this.db.deleteDone(acceptedIds);
+                this.onEventSynced?.(acceptedIds);
+            }
+            else {
+                // Complete success: delete all from local queue
+                await this.db.deleteDone(eventIds);
+                this.onEventSynced?.(eventIds);
+            }
+            if (this.debug)
+                console.log(`[Tracking Sync] Sync success: ${result.accepted || events.length} accepted.`);
+            // Keep flushing queue if there is more data pending
+            const moreEvents = await this.db.getPendingEvents(1);
+            if (moreEvents.length > 0) {
+                setTimeout(() => this.syncNow(), 100);
+            }
+            return;
+        }
+        const statusCode = response.status;
+        if (this.debug) {
+            console.warn(`[Tracking Sync] Server responded with error status: ${statusCode}`);
+            try {
+                const errBody = await response.clone().json();
+                console.error('[Tracking Sync] Server error details:', errBody);
+            }
+            catch (e) {
+                try {
+                    const errText = await response.clone().text();
+                    console.error('[Tracking Sync] Server error text:', errText);
+                }
+                catch (e2) { }
+            }
+        }
+        // -- Status 401: Unauthorized -> Refresh Token Flow --
+        if (statusCode === 401 && !isRetry && this.onRefreshToken) {
+            if (this.debug)
+                console.log('[Tracking Sync] Token expired (401). Initiating refresh token...');
+            try {
+                const refreshResult = await this.onRefreshToken();
+                if (refreshResult) {
+                    const newToken = typeof refreshResult === 'string' ? refreshResult : await this.getJwtToken();
+                    if (this.debug)
+                        console.log('[Tracking Sync] Token refreshed. Retrying sync once.');
+                    const retryResponse = await this.sendBatchWithTimeout(events, newToken, 15000);
+                    await this.handleResponse(retryResponse, events, newToken, true);
+                    return;
+                }
+            }
+            catch (err) {
+                if (this.debug)
+                    console.error('[Tracking Sync] Token refresh crashed:', err);
+            }
+            // If refresh failed, revert to pending and request re-login
+            await this.db.updateStatus(eventIds, 'pending');
+            throw new Error('Authentication expired. Re-login is required.');
+        }
+        // -- Status 400 / 403 / 422: Permanent Failures -> dead_letter --
+        if (statusCode === 400 || statusCode === 403 || statusCode === 422) {
+            const reason = statusCode === 422 ? 'HMAC_VERIFICATION_FAILED' : `PERMANENT_HTTP_ERROR_${statusCode}`;
+            for (const event of events) {
+                await this.handlePermanentFailure(event, reason);
+            }
+            return;
+        }
+        // -- Status 429 / 5xx: Temporary Failures -> backoff retry --
+        if (statusCode === 429 || statusCode >= 500) {
+            await this.handleTemporaryFailure(events, `Temporary HTTP Error ${statusCode}`);
+            return;
+        }
+        // fallback for any other codes
+        await this.handleTemporaryFailure(events, `HTTP Error ${statusCode}`);
+    }
+    async handlePermanentFailure(event, reason) {
+        if (this.debug)
+            console.warn(`[Tracking Sync] Event ${event.event_id} failed permanently: ${reason}`);
+        // Set status to dead_letter directly to prevent retries
+        await this.db.updateStatus([event.event_id], 'dead_letter', reason);
+        // Call callback for external alerting
+        this.onDeadLetter?.({
+            ...event,
+            status: 'dead_letter',
+            error_message: reason
+        });
+    }
+    async handleTemporaryFailure(events, reason) {
+        const eventIds = events.map(e => e.event_id);
+        if (this.debug)
+            console.warn(`[Tracking Sync] Batch failed temporarily: ${reason}`);
+        for (const event of events) {
+            if (event.retry_count >= this.maxRetryCount) {
+                // Move to dead letter queue if exceeded max retries
+                await this.handlePermanentFailure(event, `EXCEEDED_MAX_RETRIES (${this.maxRetryCount})`);
+            }
+            else {
+                // Return event to pending status so it can be retried in the next batch
+                await this.db.updateStatus([event.event_id], 'pending');
+            }
+        }
+        throw new Error(`Sync temporarily suspended: ${reason}`);
+    }
+    scheduleBackoff() {
+        if (this.backoffTimeout)
+            clearTimeout(this.backoffTimeout);
+        const delay = this.backoffDelays[this.backoffIndex];
+        if (this.debug)
+            console.log(`[Tracking Sync] Scheduling next retry in ${delay / 1000} seconds (backoff level ${this.backoffIndex + 1})`);
+        this.backoffTimeout = setTimeout(() => {
+            this.syncNow();
+        }, delay);
+        // Advance backoff, capping at the maximum backoff duration (10 minutes)
+        if (this.backoffIndex < this.backoffDelays.length - 1) {
+            this.backoffIndex++;
+        }
+    }
+}

package/dist/test.txt

@@ -0,0 +1 @@
+test

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+export type EventStatus = 'pending' | 'syncing' | 'done' | 'failed' | 'dead_letter';
+export interface LearningEventPayload {
+    event_name: string;
+    [key: string]: any;
+}
+export interface IframeTrackingMessage {
+    type: 'LEARNING_EVENT';
+    event_id?: string;
+    payload: LearningEventPayload;
+    timestamp: number;
+    signature?: string;
+    nonce?: string;
+}
+export interface TrackingEvent {
+    event_id: string;
+    user_id: string;
+    session_id?: string;
+    app_id: string;
+    event_name: string;
+    payload: LearningEventPayload;
+    signature?: string;
+    timestamp: number;
+    client_timestamp: number;
+    status: EventStatus;
+    retry_count: number;
+    error_message?: string;
+    created_at: number;
+}
+export interface IframeHandshakeInit {
+    type: 'INIT_HANDSHAKE';
+    nonce?: string;
+    hmacSecret?: string;
+    channel?: string;
+}
+export interface IframeHandshakeAck {
+    type: 'HANDSHAKE_ACK';
+    nonce?: string;
+}
+export interface BatchSyncResponse {
+    status: 'ok' | 'error';
+    accepted: number;
+    duplicate: number;
+    rejected: number;
+    rejected_details?: Array<{
+        event_id: string;
+        reason: string;
+    }>;
+    batch_id?: string;
+    message?: string;
+}
+export interface IframeHostTrackerConfig {
+    iframeUrl: string;
+    trustedOrigins: string[];
+    userId: string;
+    sessionId?: string;
+    appId: string;
+    appVersion?: string;
+    hmacSecret?: string;
+    apiEndpoint: string;
+    getJwtToken: () => Promise<string> | string;
+    onRefreshToken?: () => Promise<boolean | string>;
+    batchIntervalMs?: number;
+    maxQueueSize?: number;
+    maxRetryCount?: number;
+    onSyncStatusChange?: (status: 'idle' | 'syncing' | 'error') => void;
+    onEventReceived?: (event: TrackingEvent) => void;
+    onEventSynced?: (eventIds: string[]) => void;
+    onDeadLetter?: (event: TrackingEvent) => void;
+    /**
+     * Called when the game emits unit_restart or unit_start.
+     * The host can use this to update UI/debug state. Restart is treated as a new attempt
+     * by the backend through the unit_restart event itself, not by changing session_id.
+     */
+    onSessionRefreshNeeded?: (eventName: string) => void;
+    debug?: boolean;
+    sectionId?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "iframe-tracking-sdk",
+  "version": "1.0.0",
+  "description": "SDK for secure and resilient Iframe tracking progress, offline queues, and automatic sync with backoff.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "iframe",
+    "tracking",
+    "nextjs",
+    "vite",
+    "indexeddb",
+    "security"
+  ],
+  "author": "Hai Nguyen",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.0.0"
+  }
+}