Logs SDK

Un SDK de logging robusto y fácil de usar para aplicaciones web y React Native que permite rastrear eventos, errores y comportamiento del usuario con información detallada del dispositivo.

🚀 Características

• Singleton Pattern: Una sola instancia del SDK en toda la aplicación
• Detección automática de dispositivo: Recopila información del navegador/dispositivo automáticamente
• Eventos predefinidos: Más de 25 eventos comunes listos para usar
• Gestión de procesos: Agrupa logs por sesiones/procesos
• Soporte multiplataforma: Compatible con web y React Native
• TypeScript: Completamente tipado para mejor experiencia de desarrollo

📦 Instalación

npm install soad-logs
# o
yarn add soad-logs

🔧 Configuración inicial

import { logsSDK, DefaultEvents, ProcessType } from 'soad-logs';

// Configurar el cliente ID (requerido)
logsSDK.setClientId('tu-client-id-unico');

// Opcional: Configurar información del dispositivo manualmente
logsSDK.setDeviceInfo({
userAgent: 'Custom User Agent',
platform: 'iOS',
// ... más información
});

📖 Uso básico

1. Iniciar un proceso

// Iniciar un nuevo proceso de logging
const processId = await logsSDK.startProcess();
console.log('Proceso iniciado:', processId);

2. Enviar logs

// Log básico
await logsSDK.log({
eventName: 'User Action',
description: 'Usuario hizo clic en el botón principal',
processType: ProcessType.info,
userInfo: 'user123',
extras: JSON.stringify({ buttonId: 'main-cta' })
});

// Usando eventos predefinidos
await logsSDK.log({
...DefaultEvents.ButtonClicked('login-button'),
processType: ProcessType.info,
userInfo: 'user123'
});

3. Gestión de procesos

// Obtener el proceso actual
const currentProcess = logsSDK.getCurrentProcessId();

// Resetear el proceso (para iniciar uno nuevo)
logsSDK.resetProcess();

// Usar un proceso específico
await logsSDK.log({
eventName: 'Custom Event',
description: 'Evento con proceso específico',
processType: ProcessType.success,
processId: 'proceso-especifico-123'
});

🎯 Eventos predefinidos

El SDK incluye eventos predefinidos para casos de uso comunes:

Ciclo de vida de la app

DefaultEvents.AppOpen
DefaultEvents.AppClosed
DefaultEvents.AppBackground
DefaultEvents.AppForeground

Navegación

DefaultEvents.ScreenEntered('home')
DefaultEvents.ScreenExited('profile')

Acciones del usuario

DefaultEvents.ButtonClicked('submit-btn')
DefaultEvents.LinkClicked('https://example.com')
DefaultEvents.FormSubmitted('contact-form')
DefaultEvents.ItemSelected('product-123')
DefaultEvents.ToggleChanged('notifications', true)

Autenticación

DefaultEvents.UserLoggedIn('email')
DefaultEvents.UserLoggedOut
DefaultEvents.UserSignedUp('google')
DefaultEvents.PasswordChanged

Errores y mensajes

DefaultEvents.ErrorOccurred('Network timeout')
DefaultEvents.WarningOccurred('Low battery')
DefaultEvents.InfoMessage('Data synced successfully')

Notificaciones

DefaultEvents.PushNotificationReceived('New message')
DefaultEvents.PushNotificationOpened('Promotion alert')

Compras

DefaultEvents.PurchaseInitiated('premium-plan')
DefaultEvents.PurchaseCompleted('premium-plan')
DefaultEvents.PurchaseFailed('premium-plan')

Permisos del dispositivo

DefaultEvents.LocationAccessGranted
DefaultEvents.CameraAccessGranted
DefaultEvents.MicrophoneAccessGranted
DefaultEvents.DeviceOrientationChanged('landscape')

🔍 Ejemplo completo

import { logsSDK, DefaultEvents, ProcessType } from 'soad-logs';

class AppLogger {
async initialize() {
// Configurar el SDK
logsSDK.setClientId('mi-app-v1.0');

    // Iniciar proceso
    await logsSDK.startProcess();
    
    // Log de apertura de app
    await logsSDK.log({
      ...DefaultEvents.AppOpen,
      processType: ProcessType.info,
      userInfo: 'anonymous-user'
    });
}

async logUserAction(action: string, details?: any) {
await logsSDK.log({
...DefaultEvents.ButtonClicked(action),
processType: ProcessType.info,
extras: details ? JSON.stringify(details) : undefined
});
}

async logError(error: Error) {
await logsSDK.log({
...DefaultEvents.ErrorOccurred(error.message),
processType: ProcessType.error,
extras: JSON.stringify({
stack: error.stack,
timestamp: new Date().toISOString()
})
});
}
}

// Uso
const logger = new AppLogger();
await logger.initialize();
await logger.logUserAction('purchase', { productId: 'pro-plan' });

📱 Información del dispositivo

El SDK recopila automáticamente la siguiente información del dispositivo:

• userAgent: Información del navegador/app
• language: Idioma del dispositivo
• platform: Plataforma (iOS, Android, Web)
• screenResolution: Resolución de pantalla
• pixelRatio: Ratio de píxeles
• windowSize: Tamaño de ventana
• connection: Tipo de conexión de red
• connectionDownLink: Velocidad de descarga

🔧 API Reference

LogsSDK

Métodos principales

• setClientId(clientId: string): Configura el ID del cliente
• setDeviceInfo(deviceInfo: DeviceInfo): Configura información del dispositivo manualmente
• startProcess(): Promise<string>: Inicia un nuevo proceso y retorna su ID
• log(payload: LogPayload): Promise<any>: Envía un log
• resetProcess(): Resetea el proceso actual
• getCurrentProcessId(): string | null: Obtiene el ID del proceso actual

Tipos

ProcessType

enum ProcessType {
success = 'success',
error = 'error',
warning = 'warning',
info = 'info'
}

LogPayload

interface LogPayload {
eventName: string;
description: string;
userInfo?: string;
extras?: string;
processId?: string;
processType: ProcessType;
}

DeviceInfo

interface DeviceInfo {
userAgent?: string;
language?: string;
platform?: string;
screenResolution?: string;
pixelRatio?: string;
windowSize?: string;
connection?: string;
connectionDownLink?: string;
cameras?: string;
geolocation?: string;
}

🚨 Manejo de errores

try {
await logsSDK.startProcess();
} catch (error) {
console.error('Error al iniciar proceso:', error);
// El SDK lanzará errores si no se configura clientId
}

try {
await logsSDK.log({
eventName: 'Test Event',
description: 'Evento de prueba',
processType: ProcessType.info
});
} catch (error) {
console.error('Error al enviar log:', error);
// Error si no hay processId disponible
}

🌐 Soporte para React Native

El SDK es compatible con React Native. En entornos móviles, la detección automática de dispositivo retornará un objeto vacío, por lo que se recomienda usar setDeviceInfo() para proporcionar información específica del dispositivo móvil.

// En React Native
import { Platform } from 'react-native';

logsSDK.setDeviceInfo({
platform: Platform.OS,
// ... otra información específica del dispositivo móvil
});

📄 Licencia

MIT License - ver el archivo LICENSE para más detalles.

🤝 Contribuir

Las contribuciones son bienvenidas. Por favor, abre un issue o envía un pull request.