react-native-qalink 0.6.0 → 0.6.1

package/README.md

@@ -351,6 +351,68 @@ QALink.init({
 
 ---
 
+## 📦 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 +420,7 @@ 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) |
 | `http_request` | Request HTTP (fetch/axios) |
 | `user_log` | Logs con debug/info/warn/error/critical |
 | `custom_event` | Eventos custom con logEvent() |
@@ -445,6 +508,75 @@ 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. |
+| **`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 (solo breadcrumb). |
+| **`startPackage(screenName)`** | Inicia un Event Package para esa pantalla. |
+| **`endPackage()`** | Cierra el package activo y lo envía. |
+| **`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. |
+| **`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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-qalink",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Real-time error capture SDK for React Native — helps QA teams identify if bugs are frontend or backend",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",