@scalebun/react-native 1.0.2 → 1.0.3

package/src/features/session/JourneyEventPipeline.ts

@@ -1,273 +1,273 @@
-/**
- * ScaleBun SDK — Journey Event Pipeline
- *
- * Bounded ring buffer for session events with:
- * - Configurable max capacity
- * - Backpressure: drops lowest-priority events when full
- * - Crash-adjacent/error events are preserved over generic events
- * - Canonical event creation with deduplication
- * - Event emission callback for transport
- */
-
-import { logger } from '../../core/logger/internalLogger';
-import type {
-    JourneyEvent,
-    JourneyEventType,
-    JourneyEventSeverity,
-    JourneyEventSource,
-    SessionArtifactIndex,
-    CrashAnchor,
-} from './sessionTypes';
-import { EventRetentionPriority, getEventRetentionPriority } from './sessionTypes';
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-
-export type EventEmitCallback = (event: JourneyEvent) => void;
-
-interface PipelineConfig {
-    maxEventCount: number;
-    /** Window for crash anchoring: how many events either side of a crash to protect */
-    crashAnchorWindow: number;
-    /** Minimum ms between identical events to avoid rapid-fire duplicates */
-    dedupeWindowMs: number;
-}
-
-const DEFAULT_PIPELINE_CONFIG: PipelineConfig = {
-    maxEventCount: 1000,
-    crashAnchorWindow: 20,
-    dedupeWindowMs: 100,
-};
-
-// ─── Pipeline ───────────────────────────────────────────────────────────────
-
-export class JourneyEventPipeline {
-    private events: JourneyEvent[] = [];
-    private config: PipelineConfig;
-    private sessionId: string;
-    private onEmit: EventEmitCallback | null = null;
-
-    /** Set of eventIds that are crash-anchored (never drop) */
-    private protectedEventIds = new Set<string>();
-
-    /** Track last event type+subtype+ts+confidence for dedup */
-    private lastEventKey = '';
-    private lastEventTs = 0;
-    private lastEventConfidence: string | null = null;
-
-    constructor(sessionId: string, config?: Partial<PipelineConfig>) {
-        this.sessionId = sessionId;
-        this.config = { ...DEFAULT_PIPELINE_CONFIG, ...config };
-    }
-
-    // ─── Public API ─────────────────────────────────────────────────────
-
-    /** Set the callback invoked when an event is added */
-    setEmitCallback(cb: EventEmitCallback): void {
-        this.onEmit = cb;
-    }
-
-    /** Get all events (read-only snapshot) */
-    getEvents(): readonly JourneyEvent[] {
-        return this.events;
-    }
-
-    /** Current event count */
-    get count(): number {
-        return this.events.length;
-    }
-
-    /**
-     * Create and add a canonical event.
-     * Handles deduplication, retention, and emission.
-     */
-    emit(
-        type: JourneyEventType,
-        opts?: {
-            subtype?: string;
-            severity?: JourneyEventSeverity;
-            screen?: string;
-            payload?: Record<string, unknown>;
-            correlationId?: string;
-            traceId?: string;
-            source?: JourneyEventSource;
-            journeyId?: string;
-        },
-    ): JourneyEvent | null {
-        try {
-            const key = `${type}:${opts?.subtype ?? ''}`;
-            const now = Date.now();
-            if (key === this.lastEventKey && (now - this.lastEventTs) < this.config.dedupeWindowMs) {
-                // Within dedup window — allow high-confidence native events to
-                // REPLACE a prior low-confidence JS event for the same gesture.
-                // This prevents the race where JS fires first and the pipeline
-                // drops the native event that has more accurate coordinates.
-                const incomingConfidence = (opts?.payload as any)?.confidence;
-                if (incomingConfidence === 'high' && this.lastEventConfidence !== 'high') {
-                    this._replaceLastEvent(key, now, opts);
-                }
-                return null;
-            }
-            this.lastEventKey = key;
-            this.lastEventTs = now;
-            this.lastEventConfidence = (opts?.payload as any)?.confidence ?? null;
-
-            const event: JourneyEvent = {
-                eventId: generateEventId(),
-                sessionId: this.sessionId,
-                journeyId: opts?.journeyId,
-                ts: now,
-                type,
-                subtype: opts?.subtype,
-                severity: opts?.severity ?? inferSeverity(type),
-                screen: opts?.screen,
-                payload: opts?.payload,
-                correlationId: opts?.correlationId,
-                traceId: opts?.traceId,
-                source: opts?.source ?? 'sdk',
-            };
-
-            this._addEvent(event);
-            return event;
-        } catch (err) {
-            logger.error('[JourneyEventPipeline] emit failed:', err);
-            return null;
-        }
-    }
-
-    /**
-     * Anchor a crash event — protect nearby events from eviction.
-     */
-    anchorCrash(crashEventId: string): CrashAnchor {
-        const crashIdx = this.events.findIndex(e => e.eventId === crashEventId);
-        const window = this.config.crashAnchorWindow;
-
-        const start = Math.max(0, crashIdx - window);
-        const end = Math.min(this.events.length - 1, crashIdx + window);
-
-        const nearbyEventIds: string[] = [];
-        for (let i = start; i <= end; i++) {
-            nearbyEventIds.push(this.events[i].eventId);
-            this.protectedEventIds.add(this.events[i].eventId);
-        }
-
-        const crashEvent = crashIdx >= 0 ? this.events[crashIdx] : null;
-
-        return {
-            crashEventId,
-            nearbyEventIds,
-            nearbyFrameIds: [], // Filled by SessionManager (cross-references frames)
-            timestamp: crashEvent?.ts ?? Date.now(),
-        };
-    }
-
-    /**
-     * Build the event portion of the artifact index.
-     */
-    buildEventRefs(): Pick<SessionArtifactIndex, 'eventRefs' | 'networkRefs' | 'logRefs'> {
-        const eventRefs: string[] = [];
-        const networkRefs: string[] = [];
-        const logRefs: string[] = [];
-
-        for (const e of this.events) {
-            eventRefs.push(e.eventId);
-            if (e.type.startsWith('NETWORK_REQUEST')) {
-                networkRefs.push(e.eventId);
-            }
-            if (e.type === 'LOG_EMITTED') {
-                logRefs.push(e.eventId);
-            }
-        }
-
-        return { eventRefs, networkRefs, logRefs };
-    }
-
-    /** Clear all events (used on session end) */
-    clear(): void {
-        this.events = [];
-        this.protectedEventIds.clear();
-        this.lastEventKey = '';
-        this.lastEventTs = 0;
-        this.lastEventConfidence = null;
-    }
-
-    // ─── Internals ──────────────────────────────────────────────────────
-
-    private _replaceLastEvent(
-        key: string,
-        now: number,
-        opts?: { payload?: Record<string, unknown>; [k: string]: unknown },
-    ): void {
-        for (let i = this.events.length - 1; i >= 0; i--) {
-            const ev = this.events[i];
-            const evKey = `${ev.type}:${ev.subtype ?? ''}`;
-            if (evKey === key && (now - ev.ts) < this.config.dedupeWindowMs) {
-                ev.payload = opts?.payload;
-                this.lastEventConfidence = (opts?.payload as any)?.confidence ?? null;
-                logger.debug('[JourneyEventPipeline] replaced low-confidence event with native-high');
-                // Re-emit so transport receives the corrected coordinates.
-                // Backend uses upsert on eventId, so this overwrites the stale record.
-                try { this.onEmit?.(ev); } catch { /* transport must not crash pipeline */ }
-                break;
-            }
-        }
-    }
-
-    private _addEvent(event: JourneyEvent): void {
-        // If at capacity, evict lowest-priority unprotected event
-        if (this.events.length >= this.config.maxEventCount) {
-            this._evictLowestPriority();
-        }
-
-        this.events.push(event);
-
-        // Emit to transport
-        try {
-            this.onEmit?.(event);
-        } catch {
-            // Transport emission must not crash pipeline
-        }
-    }
-
-    /**
-     * Evict the oldest event with the lowest retention priority,
-     * skipping crash-anchored/protected events.
-     */
-    private _evictLowestPriority(): void {
-        let lowestIdx = -1;
-        let lowestPriority = Infinity;
-
-        for (let i = 0; i < this.events.length; i++) {
-            const event = this.events[i];
-            // Never evict protected events
-            if (this.protectedEventIds.has(event.eventId)) continue;
-
-            const priority = getEventRetentionPriority(event.type);
-            if (priority < lowestPriority) {
-                lowestPriority = priority;
-                lowestIdx = i;
-            }
-        }
-
-        if (lowestIdx >= 0) {
-            this.events.splice(lowestIdx, 1);
-        } else {
-            // All events are protected — drop oldest anyway
-            this.events.shift();
-        }
-    }
-}
-
-// ─── Helpers ────────────────────────────────────────────────────────────────
-
-function generateEventId(): string {
-    return `evt-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`;
-}
-
-function inferSeverity(type: JourneyEventType): JourneyEventSeverity {
-    switch (type) {
-        case 'CRASH_CAPTURED': return 'fatal';
-        case 'ERROR_CAPTURED': return 'error';
-        case 'NETWORK_REQUEST_FAILED': return 'warning';
-        default: return 'info';
-    }
-}
+/**
+ * ScaleBun SDK — Journey Event Pipeline
+ *
+ * Bounded ring buffer for session events with:
+ * - Configurable max capacity
+ * - Backpressure: drops lowest-priority events when full
+ * - Crash-adjacent/error events are preserved over generic events
+ * - Canonical event creation with deduplication
+ * - Event emission callback for transport
+ */
+
+import { logger } from '../../core/logger/internalLogger';
+import type {
+    JourneyEvent,
+    JourneyEventType,
+    JourneyEventSeverity,
+    JourneyEventSource,
+    SessionArtifactIndex,
+    CrashAnchor,
+} from './sessionTypes';
+import { EventRetentionPriority, getEventRetentionPriority } from './sessionTypes';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type EventEmitCallback = (event: JourneyEvent) => void;
+
+interface PipelineConfig {
+    maxEventCount: number;
+    /** Window for crash anchoring: how many events either side of a crash to protect */
+    crashAnchorWindow: number;
+    /** Minimum ms between identical events to avoid rapid-fire duplicates */
+    dedupeWindowMs: number;
+}
+
+const DEFAULT_PIPELINE_CONFIG: PipelineConfig = {
+    maxEventCount: 1000,
+    crashAnchorWindow: 20,
+    dedupeWindowMs: 100,
+};
+
+// ─── Pipeline ───────────────────────────────────────────────────────────────
+
+export class JourneyEventPipeline {
+    private events: JourneyEvent[] = [];
+    private config: PipelineConfig;
+    private sessionId: string;
+    private onEmit: EventEmitCallback | null = null;
+
+    /** Set of eventIds that are crash-anchored (never drop) */
+    private protectedEventIds = new Set<string>();
+
+    /** Track last event type+subtype+ts+confidence for dedup */
+    private lastEventKey = '';
+    private lastEventTs = 0;
+    private lastEventConfidence: string | null = null;
+
+    constructor(sessionId: string, config?: Partial<PipelineConfig>) {
+        this.sessionId = sessionId;
+        this.config = { ...DEFAULT_PIPELINE_CONFIG, ...config };
+    }
+
+    // ─── Public API ─────────────────────────────────────────────────────
+
+    /** Set the callback invoked when an event is added */
+    setEmitCallback(cb: EventEmitCallback): void {
+        this.onEmit = cb;
+    }
+
+    /** Get all events (read-only snapshot) */
+    getEvents(): readonly JourneyEvent[] {
+        return this.events;
+    }
+
+    /** Current event count */
+    get count(): number {
+        return this.events.length;
+    }
+
+    /**
+     * Create and add a canonical event.
+     * Handles deduplication, retention, and emission.
+     */
+    emit(
+        type: JourneyEventType,
+        opts?: {
+            subtype?: string;
+            severity?: JourneyEventSeverity;
+            screen?: string;
+            payload?: Record<string, unknown>;
+            correlationId?: string;
+            traceId?: string;
+            source?: JourneyEventSource;
+            journeyId?: string;
+        },
+    ): JourneyEvent | null {
+        try {
+            const key = `${type}:${opts?.subtype ?? ''}`;
+            const now = Date.now();
+            if (key === this.lastEventKey && (now - this.lastEventTs) < this.config.dedupeWindowMs) {
+                // Within dedup window — allow high-confidence native events to
+                // REPLACE a prior low-confidence JS event for the same gesture.
+                // This prevents the race where JS fires first and the pipeline
+                // drops the native event that has more accurate coordinates.
+                const incomingConfidence = (opts?.payload as any)?.confidence;
+                if (incomingConfidence === 'high' && this.lastEventConfidence !== 'high') {
+                    this._replaceLastEvent(key, now, opts);
+                }
+                return null;
+            }
+            this.lastEventKey = key;
+            this.lastEventTs = now;
+            this.lastEventConfidence = (opts?.payload as any)?.confidence ?? null;
+
+            const event: JourneyEvent = {
+                eventId: generateEventId(),
+                sessionId: this.sessionId,
+                journeyId: opts?.journeyId,
+                ts: now,
+                type,
+                subtype: opts?.subtype,
+                severity: opts?.severity ?? inferSeverity(type),
+                screen: opts?.screen,
+                payload: opts?.payload,
+                correlationId: opts?.correlationId,
+                traceId: opts?.traceId,
+                source: opts?.source ?? 'sdk',
+            };
+
+            this._addEvent(event);
+            return event;
+        } catch (err) {
+            logger.error('[JourneyEventPipeline] emit failed:', err);
+            return null;
+        }
+    }
+
+    /**
+     * Anchor a crash event — protect nearby events from eviction.
+     */
+    anchorCrash(crashEventId: string): CrashAnchor {
+        const crashIdx = this.events.findIndex(e => e.eventId === crashEventId);
+        const window = this.config.crashAnchorWindow;
+
+        const start = Math.max(0, crashIdx - window);
+        const end = Math.min(this.events.length - 1, crashIdx + window);
+
+        const nearbyEventIds: string[] = [];
+        for (let i = start; i <= end; i++) {
+            nearbyEventIds.push(this.events[i].eventId);
+            this.protectedEventIds.add(this.events[i].eventId);
+        }
+
+        const crashEvent = crashIdx >= 0 ? this.events[crashIdx] : null;
+
+        return {
+            crashEventId,
+            nearbyEventIds,
+            nearbyFrameIds: [], // Filled by SessionManager (cross-references frames)
+            timestamp: crashEvent?.ts ?? Date.now(),
+        };
+    }
+
+    /**
+     * Build the event portion of the artifact index.
+     */
+    buildEventRefs(): Pick<SessionArtifactIndex, 'eventRefs' | 'networkRefs' | 'logRefs'> {
+        const eventRefs: string[] = [];
+        const networkRefs: string[] = [];
+        const logRefs: string[] = [];
+
+        for (const e of this.events) {
+            eventRefs.push(e.eventId);
+            if (e.type.startsWith('NETWORK_REQUEST')) {
+                networkRefs.push(e.eventId);
+            }
+            if (e.type === 'LOG_EMITTED') {
+                logRefs.push(e.eventId);
+            }
+        }
+
+        return { eventRefs, networkRefs, logRefs };
+    }
+
+    /** Clear all events (used on session end) */
+    clear(): void {
+        this.events = [];
+        this.protectedEventIds.clear();
+        this.lastEventKey = '';
+        this.lastEventTs = 0;
+        this.lastEventConfidence = null;
+    }
+
+    // ─── Internals ──────────────────────────────────────────────────────
+
+    private _replaceLastEvent(
+        key: string,
+        now: number,
+        opts?: { payload?: Record<string, unknown>; [k: string]: unknown },
+    ): void {
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            const ev = this.events[i];
+            const evKey = `${ev.type}:${ev.subtype ?? ''}`;
+            if (evKey === key && (now - ev.ts) < this.config.dedupeWindowMs) {
+                ev.payload = opts?.payload;
+                this.lastEventConfidence = (opts?.payload as any)?.confidence ?? null;
+                logger.debug('[JourneyEventPipeline] replaced low-confidence event with native-high');
+                // Re-emit so transport receives the corrected coordinates.
+                // Backend uses upsert on eventId, so this overwrites the stale record.
+                try { this.onEmit?.(ev); } catch { /* transport must not crash pipeline */ }
+                break;
+            }
+        }
+    }
+
+    private _addEvent(event: JourneyEvent): void {
+        // If at capacity, evict lowest-priority unprotected event
+        if (this.events.length >= this.config.maxEventCount) {
+            this._evictLowestPriority();
+        }
+
+        this.events.push(event);
+
+        // Emit to transport
+        try {
+            this.onEmit?.(event);
+        } catch {
+            // Transport emission must not crash pipeline
+        }
+    }
+
+    /**
+     * Evict the oldest event with the lowest retention priority,
+     * skipping crash-anchored/protected events.
+     */
+    private _evictLowestPriority(): void {
+        let lowestIdx = -1;
+        let lowestPriority = Infinity;
+
+        for (let i = 0; i < this.events.length; i++) {
+            const event = this.events[i];
+            // Never evict protected events
+            if (this.protectedEventIds.has(event.eventId)) continue;
+
+            const priority = getEventRetentionPriority(event.type);
+            if (priority < lowestPriority) {
+                lowestPriority = priority;
+                lowestIdx = i;
+            }
+        }
+
+        if (lowestIdx >= 0) {
+            this.events.splice(lowestIdx, 1);
+        } else {
+            // All events are protected — drop oldest anyway
+            this.events.shift();
+        }
+    }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function generateEventId(): string {
+    return `evt-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 8)}`;
+}
+
+function inferSeverity(type: JourneyEventType): JourneyEventSeverity {
+    switch (type) {
+        case 'CRASH_CAPTURED': return 'fatal';
+        case 'ERROR_CAPTURED': return 'error';
+        case 'NETWORK_REQUEST_FAILED': return 'warning';
+        default: return 'info';
+    }
+}