react-native-qalink 0.6.0 → 0.7.0

package/README.md

@@ -351,6 +351,184 @@ QALink.init({
 
 ---
 
+## 🧠 Advanced QA Features (v0.7.0)
+
+### Rage Click Detection
+
+Detects when a user taps the same element multiple times rapidly — a strong frustration signal.
+
+```typescript
+// 1. Enable (once, after init)
+QALink.enableRageClickDetection({ threshold: 3, windowMs: 600 });
+
+// 2. Call from any onPress handler
+<Button
+  onPress={() => {
+    QALink.trackUIInteraction('checkout-submit-btn');
+    handleSubmit();
+  }}
+/>
+```
+
+A `rage_click` event fires in the dashboard when the threshold is hit.
+
+---
+
+### Navigation Loop Detection
+
+Detects when the user bounces back and forth between the same two screens (A→B→A→B…). Signals broken back navigation or an unresolved error state.
+
+```typescript
+// Enable (once, after init)
+QALink.enableNavigationLoopDetection(3); // fires after 3 alternations
+
+// Automatically triggered by setScreen() and startPackage()
+QALink.setScreen('CheckoutScreen');
+```
+
+A `navigation_loop` event fires in the dashboard with the full navigation pattern.
+
+---
+
+### Silent Failure Detection
+
+The hardest QA bug: API returns 200 OK but the data is null/empty. No error, no crash — the app just silently breaks.
+
+```typescript
+const orders = await fetchOrders(userId); // 200 OK
+
+QALink.trackDataState({
+  context: 'orders_list',
+  expected: Array.isArray(orders) && orders.length > 0,
+  actual: orders,
+  statusCode: 200,
+  url: '/api/orders',
+});
+// If orders is [] → fires a silent_failure event in the dashboard
+```
+
+Returns `true` if the check passes, `false` if a failure was detected.
+
+---
+
+### Middleware (Event Processing Pipeline)
+
+Intercept, enrich, filter, or transform any event before it's sent.
+
+```typescript
+// Drop noisy console_log events in production
+QALink.use((event, next) => {
+  if (event.type === 'console_log') return; // drop
+  next(event);
+});
+
+// Add a custom tag to every event
+QALink.use((event, next) => {
+  next({ ...event, _release: '2.1.0' } as typeof event);
+});
+
+// Log every event locally for debugging
+QALink.use((event, next) => {
+  console.log('[QALink middleware]', event.type);
+  next(event);
+});
+```
+
+Middlewares run in insertion order. Calling `next` is optional — skipping it drops the event.
+
+---
+
+### Offline-First Queue
+
+Events are buffered automatically when the connection drops. Auto-flush triggers:
+
+```typescript
+QALink.init({
+  apiKey: 'qlk_...',
+  appVersion: '1.0.0',
+  offlineQueue: {
+    maxSize: 500,        // max buffered events (drops oldest when full)
+    flushOnCount: 20,    // auto-flush when 20 events are buffered
+    flushIntervalMs: 30_000, // auto-flush every 30s
+  },
+});
+
+// Manual flush (e.g. before app goes to background)
+QALink.flush();
+```
+
+If `@react-native-async-storage/async-storage` is installed, events also persist across app restarts.
+
+---
+
+### Sequence Numbers
+
+Every envelope sent to the dashboard now includes a `sequenceNumber` — a monotonically increasing counter per session. The dashboard can use it to detect out-of-order or missing events.
+
+---
+
+## 📦 Event Packages (v0.6.0)
+
+Los **Event Packages** agrupan **todos los eventos** de una pantalla en un solo payload que se envía cuando el usuario sale de ella. Incluyen métricas pre-calculadas y el historial completo de eventos.
+
+### Integración en 1 línea — `useTrackedScreen`
+
+```typescript
+import { useTrackedScreen } from 'react-native-qalink';
+
+function CheckoutScreen() {
+  useTrackedScreen('CheckoutScreen');
+  // ↑ inicia el package al montar, lo cierra y envía al desmontar
+  return <View>...</View>;
+}
+```
+
+Eso es todo. Todos los eventos generados mientras el usuario está en esa pantalla (API calls, logs, errores, breadcrumbs) se agrupan y se envían juntos al salir.
+
+### API manual — `startPackage` / `endPackage`
+
+```typescript
+// En React Navigation (App.tsx)
+<NavigationContainer
+  onStateChange={() => {
+    const screen = navigationRef.current?.getCurrentRoute()?.name ?? '';
+
+    QALink.endPackage();       // cierra el package de la pantalla anterior
+    QALink.startPackage(screen); // inicia uno nuevo para la pantalla actual
+  }}
+>
+```
+
+### Payload que recibe el dashboard
+
+```json
+{
+  "type": "event_package",
+  "packageId": "...",
+  "context": {
+    "screenName": "CheckoutScreen",
+    "sessionId": "...",
+    "startTime": 1710445670000,
+    "endTime":   1710445680000,
+    "durationMs": 10000
+  },
+  "events": [ ...todos los eventos capturados en esa pantalla... ],
+  "metrics": {
+    "totalApiCalls":    3,
+    "totalErrors":      1,
+    "totalLogs":        5,
+    "totalBreadcrumbs": 2,
+    "totalEvents":     11
+  }
+}
+```
+
+### Backward compatibility
+
+Si **no** llamas `startPackage` ni `useTrackedScreen`, cada evento se sigue enviando inmediatamente como antes. Sin cambios de comportamiento.
+
+---
+
 ## 📊 Tipos de eventos capturados
 
 El SDK captura automáticamente:
@@ -358,6 +536,10 @@ El SDK captura automáticamente:
 | Tipo | Descripción |
 |------|-------------|
 | `session_start` | Inicio de sesión |
+| `event_package` | Batch de eventos de una pantalla (v0.6.0) |
+| `rage_click` | Usuario tapeó el mismo elemento N veces (v0.7.0) |
+| `navigation_loop` | Usuario rebotando entre mismas pantallas (v0.7.0) |
+| `silent_failure` | API 200 OK con datos inválidos/vacíos (v0.7.0) |
 | `http_request` | Request HTTP (fetch/axios) |
 | `user_log` | Logs con debug/info/warn/error/critical |
 | `custom_event` | Eventos custom con logEvent() |
@@ -445,6 +627,82 @@ QALink.logEvent('experiment_viewed', {
 });
 ```
 
+### 4. Event Package con React Navigation
+
+```typescript
+// App.tsx
+import { useTrackedScreen } from 'react-native-qalink';
+
+// En cada pantalla — 1 sola línea:
+function PaymentScreen() {
+  useTrackedScreen('PaymentScreen');
+  // ...
+}
+
+function ProfileScreen() {
+  useTrackedScreen('ProfileScreen');
+  // ...
+}
+```
+
+O con `NavigationContainer` para cobertura automática de todas las pantallas:
+
+```typescript
+// App.tsx
+import { NavigationContainer } from '@react-navigation/native';
+import { QALink } from 'react-native-qalink';
+
+<NavigationContainer
+  onStateChange={() => {
+    const screen = navigationRef.current?.getCurrentRoute()?.name ?? 'unknown';
+    QALink.endPackage();        // cierra el package de la pantalla anterior
+    QALink.startPackage(screen); // inicia uno nuevo
+  }}
+>
+```
+
+---
+
+## 📋 Referencia completa de la API
+
+| Método | Descripción |
+|--------|-------------|
+| **`init(config)`** | Inicializa el SDK. Requerido antes de todo. |
+| **`interceptAxios(instance)`** | Registra una instancia de Axios. |
+| **`use(middleware)`** | Agrega un middleware al pipeline de eventos. |
+| **`setUserContext(ctx)`** | Adjunta datos del usuario a todos los eventos. |
+| **`setCustomContext(ctx)`** | Adjunta datos custom a todos los eventos. |
+| **`clearContext()`** | Limpia usuario y contexto custom. |
+| **`debug(...args)`** | Log nivel debug. |
+| **`info(...args)`** | Log nivel info. |
+| **`warn(...args)`** | Log nivel warn. |
+| **`error(...args)`** | Log nivel error. |
+| **`critical(...args)`** | Log nivel critical. |
+| **`logEvent(name, data?)`** | Evento custom de negocio. |
+| **`addBreadcrumb(action, data?)`** | Breadcrumb manual. |
+| **`logRequest(options)`** | Registra request de red manualmente. |
+| **`setScreen(name)`** | Cambia la pantalla actual + breadcrumb + loop detection. |
+| **`startPackage(screenName)`** | Inicia un Event Package para esa pantalla. |
+| **`endPackage()`** | Cierra el package activo y lo envía. |
+| **`flush()`** | Envía inmediatamente todos los eventos en cola offline. |
+| **`enableRageClickDetection(options?)`** | Activa detección de rage clicks. |
+| **`trackUIInteraction(target)`** | Registra tap para rage click. |
+| **`enableNavigationLoopDetection(threshold?)`** | Activa detección de loops de navegación. |
+| **`trackDataState(check)`** | Detecta silent failures (API 200 con datos inválidos). |
+| **`captureScreen(label?)`** | Captura la pantalla completa. |
+| **`captureRef(ref, label?)`** | Captura un componente específico. |
+| **`configureHTTP(config)`** | Actualiza config HTTP en runtime. |
+| **`getDeviceId()`** | Devuelve el deviceId de la sesión. |
+| **`getStatus()`** | Estado de la conexión WebSocket. |
+| **`getQueueSize()`** | Número de eventos en cola offline. |
+| **`destroy()`** | Limpia interceptores y desconecta. |
+
+**Hook:**
+
+| Hook | Descripción |
+|------|-------------|
+| **`useTrackedScreen(name)`** | 1 línea: inicia y cierra el package automáticamente al montar/desmontar la pantalla. |
+
 ---
 
 ## 🚨 Troubleshooting

package/dist/core/MiddlewarePipeline.d.ts

@@ -0,0 +1,37 @@
+/**
+ * MiddlewarePipeline — chain of event processors applied before sending.
+ *
+ * Each middleware receives an event and a `next` callback:
+ *   - Call `next(event)` to pass the (optionally modified) event forward.
+ *   - Don't call `next` to drop the event entirely.
+ *   - Mutate or replace the event to enrich/transform it.
+ *
+ * @example
+ * pipeline.use((event, next) => {
+ *   // Drop noisy console logs in production
+ *   if (event.type === 'console_log') return;
+ *   next(event);
+ * });
+ *
+ * @example
+ * pipeline.use((event, next) => {
+ *   // Enrich every event with a custom tag
+ *   next({ ...event, _tag: 'v2' } as typeof event);
+ * });
+ */
+import type { QALinkEvent } from '../types';
+export type EventMiddleware = (event: QALinkEvent, next: (event: QALinkEvent) => void) => void;
+export declare class MiddlewarePipeline {
+    private readonly middlewares;
+    /** Register a middleware. Middlewares run in insertion order. */
+    use(middleware: EventMiddleware): this;
+    /** Clear all registered middlewares. */
+    clear(): void;
+    get count(): number;
+    /**
+     * Run `event` through the full middleware chain.
+     * `finalHandler` is called only if every middleware calls `next`.
+     */
+    process(event: QALinkEvent, finalHandler: (event: QALinkEvent) => void): void;
+}
+//# sourceMappingURL=MiddlewarePipeline.d.ts.map

package/dist/core/MiddlewarePipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiddlewarePipeline.d.ts","sourceRoot":"","sources":["../../src/core/MiddlewarePipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,MAAM,MAAM,eAAe,GAAG,CAC5B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,KAC/B,IAAI,CAAC;AAEV,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IAErD,iEAAiE;IACjE,GAAG,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI;IAKtC,wCAAwC;IACxC,KAAK,IAAI,IAAI;IAIb,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;CAa9E"}

package/dist/core/MiddlewarePipeline.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * MiddlewarePipeline — chain of event processors applied before sending.
+ *
+ * Each middleware receives an event and a `next` callback:
+ *   - Call `next(event)` to pass the (optionally modified) event forward.
+ *   - Don't call `next` to drop the event entirely.
+ *   - Mutate or replace the event to enrich/transform it.
+ *
+ * @example
+ * pipeline.use((event, next) => {
+ *   // Drop noisy console logs in production
+ *   if (event.type === 'console_log') return;
+ *   next(event);
+ * });
+ *
+ * @example
+ * pipeline.use((event, next) => {
+ *   // Enrich every event with a custom tag
+ *   next({ ...event, _tag: 'v2' } as typeof event);
+ * });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiddlewarePipeline = void 0;
+class MiddlewarePipeline {
+    constructor() {
+        this.middlewares = [];
+    }
+    /** Register a middleware. Middlewares run in insertion order. */
+    use(middleware) {
+        this.middlewares.push(middleware);
+        return this;
+    }
+    /** Clear all registered middlewares. */
+    clear() {
+        this.middlewares.length = 0;
+    }
+    get count() {
+        return this.middlewares.length;
+    }
+    /**
+     * Run `event` through the full middleware chain.
+     * `finalHandler` is called only if every middleware calls `next`.
+     */
+    process(event, finalHandler) {
+        const chain = this.middlewares;
+        const run = (index, current) => {
+            if (index >= chain.length) {
+                finalHandler(current);
+                return;
+            }
+            chain[index](current, (next) => run(index + 1, next));
+        };
+        run(0, event);
+    }
+}
+exports.MiddlewarePipeline = MiddlewarePipeline;
+//# sourceMappingURL=MiddlewarePipeline.js.map

package/dist/core/MiddlewarePipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiddlewarePipeline.js","sourceRoot":"","sources":["../../src/core/MiddlewarePipeline.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;AASH,MAAa,kBAAkB;IAA/B;QACmB,gBAAW,GAAsB,EAAE,CAAC;IAkCvD,CAAC;IAhCC,iEAAiE;IACjE,GAAG,CAAC,UAA2B;QAC7B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wCAAwC;IACxC,KAAK;QACH,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,KAAkB,EAAE,YAA0C;QACpE,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC;QAE/B,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,OAAoB,EAAQ,EAAE;YACxD,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC1B,YAAY,CAAC,OAAO,CAAC,CAAC;gBACtB,OAAO;YACT,CAAC;YACD,KAAK,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QACxD,CAAC,CAAC;QAEF,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAChB,CAAC;CACF;AAnCD,gDAmCC"}

package/dist/core/OfflineQueue.d.ts

@@ -0,0 +1,48 @@
+/**
+ * OfflineQueue — FIFO event queue with optional AsyncStorage persistence.
+ *
+ * - Falls back to pure in-memory when AsyncStorage is not installed.
+ * - Respects a max-size limit (drops oldest event when full).
+ * - Supports two auto-flush triggers:
+ *     · count-based: flush when queue reaches `flushOnCount` events.
+ *     · time-based:  flush every `flushIntervalMs` milliseconds.
+ * - Persists across app restarts when AsyncStorage is available.
+ */
+import type { QALinkEvent } from '../types';
+export interface OfflineQueueConfig {
+    maxSize?: number;
+    /** Trigger flush when this many events are buffered. @default 20 */
+    flushOnCount?: number;
+    /** Trigger flush every N milliseconds. @default 30000 */
+    flushIntervalMs?: number;
+    debug?: boolean;
+}
+type FlushCallback = (events: QALinkEvent[]) => void;
+export declare class OfflineQueue {
+    private memory;
+    private readonly maxSize;
+    private readonly flushOnCount;
+    private readonly flushIntervalMs;
+    private readonly debug;
+    private flushTimer;
+    private onFlush;
+    private storage;
+    constructor(config?: OfflineQueueConfig);
+    private tryBindAsyncStorage;
+    setFlushCallback(cb: FlushCallback): void;
+    startAutoFlush(): void;
+    stopAutoFlush(): void;
+    push(event: QALinkEvent): Promise<void>;
+    /** Remove and return all buffered events. Clears persistence. */
+    drain(): QALinkEvent[];
+    peek(): readonly QALinkEvent[];
+    get size(): number;
+    /** Load events persisted from a previous session and merge into current queue. */
+    loadPersisted(): Promise<void>;
+    private persist;
+    private clearPersisted;
+    private triggerFlush;
+    private log;
+}
+export {};
+//# sourceMappingURL=OfflineQueue.d.ts.map

package/dist/core/OfflineQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OfflineQueue.d.ts","sourceRoot":"","sources":["../../src/core/OfflineQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAO5C,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,KAAK,aAAa,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC;AAQrD,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,OAAO,CAAoC;gBAEvC,MAAM,GAAE,kBAAuB;IAU3C,OAAO,CAAC,mBAAmB;IAa3B,gBAAgB,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI;IAMzC,cAAc,IAAI,IAAI;IAUtB,aAAa,IAAI,IAAI;IASf,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAc7C,iEAAiE;IACjE,KAAK,IAAI,WAAW,EAAE;IAOtB,IAAI,IAAI,SAAS,WAAW,EAAE;IAI9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID,kFAAkF;IAC5E,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;YAwBtB,OAAO;IASrB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,GAAG;CAGZ"}

package/dist/core/OfflineQueue.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * OfflineQueue — FIFO event queue with optional AsyncStorage persistence.
+ *
+ * - Falls back to pure in-memory when AsyncStorage is not installed.
+ * - Respects a max-size limit (drops oldest event when full).
+ * - Supports two auto-flush triggers:
+ *     · count-based: flush when queue reaches `flushOnCount` events.
+ *     · time-based:  flush every `flushIntervalMs` milliseconds.
+ * - Persists across app restarts when AsyncStorage is available.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineQueue = void 0;
+const STORAGE_KEY = '__qalink_offline_queue__';
+const DEFAULT_MAX_SIZE = 500;
+const DEFAULT_FLUSH_COUNT = 20;
+const DEFAULT_FLUSH_INTERVAL_MS = 30000;
+class OfflineQueue {
+    constructor(config = {}) {
+        var _a, _b, _c, _d;
+        this.memory = [];
+        this.flushTimer = null;
+        this.onFlush = null;
+        this.storage = null;
+        this.maxSize = (_a = config.maxSize) !== null && _a !== void 0 ? _a : DEFAULT_MAX_SIZE;
+        this.flushOnCount = (_b = config.flushOnCount) !== null && _b !== void 0 ? _b : DEFAULT_FLUSH_COUNT;
+        this.flushIntervalMs = (_c = config.flushIntervalMs) !== null && _c !== void 0 ? _c : DEFAULT_FLUSH_INTERVAL_MS;
+        this.debug = (_d = config.debug) !== null && _d !== void 0 ? _d : false;
+        this.tryBindAsyncStorage();
+    }
+    // ─── Setup ─────────────────────────────────────────────────────────────────
+    tryBindAsyncStorage() {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const AS = require('@react-native-async-storage/async-storage').default;
+            if (AS && typeof AS.getItem === 'function') {
+                this.storage = AS;
+                this.log('AsyncStorage persistence enabled');
+            }
+        }
+        catch (_a) {
+            this.log('AsyncStorage unavailable — in-memory queue only');
+        }
+    }
+    setFlushCallback(cb) {
+        this.onFlush = cb;
+    }
+    // ─── Auto-flush lifecycle ──────────────────────────────────────────────────
+    startAutoFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setInterval(() => {
+            if (this.memory.length > 0) {
+                this.log(`Auto-flush (time) — ${this.memory.length} events`);
+                this.triggerFlush();
+            }
+        }, this.flushIntervalMs);
+    }
+    stopAutoFlush() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    // ─── Queue operations ──────────────────────────────────────────────────────
+    async push(event) {
+        if (this.memory.length >= this.maxSize) {
+            this.memory.shift();
+            this.log('Queue full — dropped oldest event');
+        }
+        this.memory.push(event);
+        await this.persist();
+        if (this.memory.length >= this.flushOnCount) {
+            this.log(`Auto-flush (count) — ${this.memory.length} events`);
+            this.triggerFlush();
+        }
+    }
+    /** Remove and return all buffered events. Clears persistence. */
+    drain() {
+        const events = [...this.memory];
+        this.memory = [];
+        this.clearPersisted();
+        return events;
+    }
+    peek() {
+        return this.memory;
+    }
+    get size() {
+        return this.memory.length;
+    }
+    // ─── Persistence ───────────────────────────────────────────────────────────
+    /** Load events persisted from a previous session and merge into current queue. */
+    async loadPersisted() {
+        if (!this.storage)
+            return;
+        try {
+            const raw = await this.storage.getItem(STORAGE_KEY);
+            if (!raw)
+                return;
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                return;
+            const existingIds = new Set(this.memory.map((e) => e.id).filter(Boolean));
+            for (const ev of parsed) {
+                const id = ev.id;
+                if (!id || !existingIds.has(id)) {
+                    this.memory.push(ev);
+                }
+            }
+            this.log(`Loaded ${parsed.length} persisted events from previous session`);
+        }
+        catch (_a) {
+            this.log('Failed to load persisted queue — starting fresh');
+        }
+    }
+    async persist() {
+        if (!this.storage)
+            return;
+        try {
+            await this.storage.setItem(STORAGE_KEY, JSON.stringify(this.memory));
+        }
+        catch (_a) {
+            // Ignore silently — persistence is best-effort
+        }
+    }
+    clearPersisted() {
+        var _a;
+        (_a = this.storage) === null || _a === void 0 ? void 0 : _a.removeItem(STORAGE_KEY).catch(() => { });
+    }
+    // ─── Flush trigger ─────────────────────────────────────────────────────────
+    triggerFlush() {
+        if (!this.onFlush)
+            return;
+        const events = this.drain();
+        if (events.length > 0)
+            this.onFlush(events);
+    }
+    // ─── Helpers ───────────────────────────────────────────────────────────────
+    log(...args) {
+        if (this.debug)
+            console.log('[QALink OfflineQueue]', ...args);
+    }
+}
+exports.OfflineQueue = OfflineQueue;
+//# sourceMappingURL=OfflineQueue.js.map

package/dist/core/OfflineQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OfflineQueue.js","sourceRoot":"","sources":["../../src/core/OfflineQueue.ts"],"names":[],"mappings":"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"}

package/dist/core/session.d.ts

@@ -2,6 +2,8 @@ import { DeviceInfo } from '../types';
 export declare function generateId(): string;
 export declare function getSessionId(): string;
 export declare function resetSession(): string;
+export declare function nextSequenceNumber(): number;
+export declare function resetSequenceCounter(): void;
 export declare function getDeviceInfo(appVersion: string): Promise<DeviceInfo>;
 export declare function sanitizeBody(body: unknown, logBodies: boolean): unknown;
 //# sourceMappingURL=session.d.ts.map

package/dist/core/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAItC,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAKrC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmB3E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAGvE"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAKtC,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAKrC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAGrC;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmB3E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAGvE"}

package/dist/core/session.js

@@ -3,9 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateId = generateId;
 exports.getSessionId = getSessionId;
 exports.resetSession = resetSession;
+exports.nextSequenceNumber = nextSequenceNumber;
+exports.resetSequenceCounter = resetSequenceCounter;
 exports.getDeviceInfo = getDeviceInfo;
 exports.sanitizeBody = sanitizeBody;
 let currentSessionId = null;
+let sequenceCounter = 0;
 function generateId() {
     return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
 }
@@ -19,6 +22,12 @@ function resetSession() {
     currentSessionId = generateId();
     return currentSessionId;
 }
+function nextSequenceNumber() {
+    return ++sequenceCounter;
+}
+function resetSequenceCounter() {
+    sequenceCounter = 0;
+}
 async function getDeviceInfo(appVersion) {
     var _a, _b;
     try {

package/dist/core/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":";;AAIA,gCAEC;AAED,oCAKC;AAED,oCAGC;AAED,sCAmBC;AAED,oCAGC;AA1CD,IAAI,gBAAgB,GAAkB,IAAI,CAAC;AAE3C,SAAgB,UAAU;IACxB,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC;AAED,SAAgB,YAAY;IAC1B,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,gBAAgB,GAAG,UAAU,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,SAAgB,YAAY;IAC1B,gBAAgB,GAAG,UAAU,EAAE,CAAC;IAChC,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAEM,KAAK,UAAU,aAAa,CAAC,UAAkB;;IACpD,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;QAC7C,OAAO;YACL,QAAQ,EAAE,QAAQ,CAAC,EAAuB;YAC1C,SAAS,EAAE,MAAA,MAAA,QAAQ,CAAC,OAAO,0CAAE,QAAQ,EAAE,mCAAI,SAAS;YACpD,UAAU;YACV,WAAW,EAAE,SAAS;YACtB,SAAS,EAAE,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;SAC3E,CAAC;IACJ,CAAC;IAAC,WAAM,CAAC;QACP,OAAO;YACL,QAAQ,EAAE,SAAS;YACnB,SAAS,EAAE,SAAS;YACpB,UAAU;YACV,WAAW,EAAE,SAAS;YACtB,SAAS,EAAE,SAAS;SACrB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAgB,YAAY,CAAC,IAAa,EAAE,SAAkB;IAC5D,IAAI,CAAC,SAAS;QAAE,OAAO,0CAA0C,CAAC;IAClE,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":";;AAKA,gCAEC;AAED,oCAKC;AAED,oCAGC;AAED,gDAEC;AAED,oDAEC;AAED,sCAmBC;AAED,oCAGC;AAnDD,IAAI,gBAAgB,GAAkB,IAAI,CAAC;AAC3C,IAAI,eAAe,GAAG,CAAC,CAAC;AAExB,SAAgB,UAAU;IACxB,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC;AAED,SAAgB,YAAY;IAC1B,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,gBAAgB,GAAG,UAAU,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,SAAgB,YAAY;IAC1B,gBAAgB,GAAG,UAAU,EAAE,CAAC;IAChC,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,SAAgB,kBAAkB;IAChC,OAAO,EAAE,eAAe,CAAC;AAC3B,CAAC;AAED,SAAgB,oBAAoB;IAClC,eAAe,GAAG,CAAC,CAAC;AACtB,CAAC;AAEM,KAAK,UAAU,aAAa,CAAC,UAAkB;;IACpD,IAAI,CAAC;QACH,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;QAC7C,OAAO;YACL,QAAQ,EAAE,QAAQ,CAAC,EAAuB;YAC1C,SAAS,EAAE,MAAA,MAAA,QAAQ,CAAC,OAAO,0CAAE,QAAQ,EAAE,mCAAI,SAAS;YACpD,UAAU;YACV,WAAW,EAAE,SAAS;YACtB,SAAS,EAAE,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;SAC3E,CAAC;IACJ,CAAC;IAAC,WAAM,CAAC;QACP,OAAO;YACL,QAAQ,EAAE,SAAS;YACnB,SAAS,EAAE,SAAS;YACpB,UAAU;YACV,WAAW,EAAE,SAAS;YACtB,SAAS,EAAE,SAAS;SACrB,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAgB,YAAY,CAAC,IAAa,EAAE,SAAkB;IAC5D,IAAI,CAAC,SAAS;QAAE,OAAO,0CAA0C,CAAC;IAClE,OAAO,IAAI,CAAC;AACd,CAAC"}