Introducción

Pingui Alert es un servicio de notificación ligero que te permite enviar alertas a tu cuenta de Telegram directamente desde tu código. Está diseñado para ser extremadamente simple de usar, sin requerir configuración en tu servidor.

Arquitectura del Sistema

Pingui Alert utiliza una arquitectura basada en colas para garantizar la entrega confiable de alertas:

Componentes Principales

• API REST: Recibe las alertas y las encola
• Cola Redis: Almacena alertas pendientes (máx 500 alertas)
• Worker de Cola: Procesa alertas a 1 msg/segundo (límite seguro de Telegram)
• Jobs Programados: Tareas automáticas de mantenimiento
• Bot de Telegram: Interfaz para gestionar integraciones

Jobs Automáticos

El sistema ejecuta tareas de mantenimiento programadas:

• Reset de Rate Limits (00:00 diario): Reinicia el contador de alertas diarias a 10 para todos los usuarios
• Backup de Base de Datos (03:00 diario): Crea backups automáticos de la base de datos SQLite

Configuración y Autenticación

Para comenzar a enviar alertas, necesitas obtener una API Key de nuestro bot de Telegram.

1. Abre Telegram y busca @PinguiAlertBot (o tu instancia hosteada).
2. Inicia un chat y envía el comando /start para registrarte.
3. Envía el comando /temporal_token para obtener un token de acceso temporal. (Una vez que crees tu primera integración, obtendrás un nuevo token permanente)
4. Usa la API para crear tu primera integración y comenzar a enviar alertas.

Los Mandamientos

Para mantener Pingui Alert útil y estable para todos, nos adherimos a un conjunto estricto de reglas. Sigue estos mandamientos para asegurar la mejor experiencia.

1. I. Uso Crítico Solamente
   Solo lo usarás para alertas críticas que deban ser corregidas de inmediato. Diseña tu sistema para disparar estas alertas con moderación—solo una vez por tipo de incidente.
2. II. Estándares de Producción
   Si vas a enviar errores de tu api con nuestro bot, utiliza las mejores prácticas de producción. Asegúrate de que tu manejo de errores es robusto antes de enviarlo como alerta.
3. III. Self-Host para Customización
   Si requieres alguna customización (por simple que sea), utiliza la opción de self hosted. Puedes hostear Pingui Alert en cualquier lugar; sugerimos un VPS o servidor local por los pocos recursos que consume.
4. IV. Alertas Accionables
   Asegurarás que cada alerta sea accionable. Cada alerta debe incitar una respuesta específica e inmediata.
5. V. Sin Fugas de Datos
   No enviarás datos sensibles de usuarios (PII), identificadores o secretos en tus alertas. Mantén los mensajes seguros.
6. VI. Fallar de Forma Segura
   Implementarás manejo de errores para que una notificación de alerta fallida nunca bloquee tu aplicación principal. El fallo del servicio de alertas debe ser silencioso para tus usuarios finales.

Self-Hosting

Pingui Alert es completamente open source y puede ser auto-hosteado para control total sobre tu infraestructura de alertas.

Prerequisitos

• Node.js: v20 o superior
• pnpm: v9 o superior
• Redis: Para el sistema de colas (local o hosteado)
• Token de Bot de Telegram: Crear vía @BotFather

Configuración Rápida

git clone https://github.com/juanvidev1/pingui-alert
cd pingui-alert
pnpm install

# Configurar entorno
cp .env.example .env
# Editar .env con tus valores

# Ejecutar en desarrollo
pnpm run dev

# O compilar para producción
pnpm run build
pnpm run start

Variables de Entorno

# Requeridas
BOT_TOKEN=tu_token_de_telegram
JWT_SECRET=tu_jwt_secreto
REDIS_URL=redis://localhost:6379

# Opcionales
MAX_ALERTS=100  # Personalizar límite diario
MAX_QUEUE_SIZE=500
SEND_DELAY_MS=1000

Monitoreo y Logs

Pingui Alert proporciona capacidades completas de logging y monitoreo:

Archivos de Log

• logs/info.log: Eventos generales y alertas procesadas
• logs/error.log: Errores de aplicación y fallos de envío
• logs/jobs.log: Ejecución de jobs programados

Comandos de Monitoreo

# Ver alertas en tiempo real
tail -f logs/info.log | grep "Sending alert"

# Monitorear errores
tail -f logs/error.log

# Verificar estado de jobs
tail -f logs/jobs.log

# Tamaño de cola Redis
redis-cli LLEN pingui:queue:alerts

Métricas del Sistema

Rastrea el uso del sistema y rendimiento con métricas integradas:

Métricas Disponibles

• Total de Integraciones: Número de integraciones registradas
• Total de Alertas Enviadas: Alertas entregadas acumulativas
• Total de Errores: Intentos de alerta fallidos
• Última Actualización: Timestamp de frescura de métricas

Respuesta de Ejemplo

{
  "totalIntegrations": 1234,
  "totalSentAlerts": 45678,
  "totalErrors": 23,
  "metrics": [
    {
      "totalIntegrations": 1234,
      "totalSentAlerts": 45678,
      "totalErrors": 23,
      "updatedAt": "2025-01-01T12:00:00Z"
    }
  ]
}

Uso en Producción

Cuando uses Pingui Alert en entornos de producción, sigue estas mejores prácticas para asegurar un servicio óptimo para todos.

Configuración Recomendada para Producción

Para cargas de trabajo en producción con notificaciones frecuentes, recomendamos uno de estos enfoques:

• Hostea tu propia Instancia: Despliega tu propio servidor y bot de Pingui Alert. Esto te da control total sobre los límites de tasa y recursos dedicados.
• Solo Alertas Críticas: Si usas @PinguiAlertBot, implementa lógica de filtrado para enviar solo notificaciones de alta prioridad.
• Implementa Batching: Agrupa múltiples alertas no críticas en mensajes de resumen periódicos en lugar de enviar notificaciones individuales.

Comandos del Bot de Telegram

Toda interacción con Pingui Alert comienza desde el bot de Telegram. Aquí tienes la referencia completa de los comandos disponibles.

Comandos Generales

/help

/get_me

/temporal_token

Comandos de Miembro

/join ABC123

Comandos Solo para Propietarios

Estos comandos requieren una integración activa y están restringidos al propietario de la integración.

/join_owner

/create_invite

/get_members

Paquete NPM

Si usas Node.js o TypeScript, te recomendamos usar nuestro paquete oficial en caso de que solo quieras enviar alertas usando el servidor Pingui Alert. El límite de tasa y la cuota son manejados por el servidor y aún necesitas usar el endpoint createIntegration para obtener tu API KEY.

Instalación

npm install pingui-alert

Uso

import { PinguiAlert } from 'pingui-alert-sdk';

const pinguiAlert = new PinguiAlert({
  chatId: process.env.PINGUI_ALERT_CHAT_ID,
  token: process.env.PINGUI_ALERT_API_KEY,
});

// Opcional: Validar el estado de la integración antes de enviar una alerta. Esto verifica si la integración está activa y tiene cuota.
const pinguiStatus = await pinguiAlert.validateStatus();
console.log('Estado de Pingui Alert:', pinguiStatus); // Ejemplo de respuesta exitosa: { success: true, remainingAlerts: 9 }

// Este método permite enviar una alerta. El primer parámetro es el mensaje que se enviará. El segundo parámetro es opcional y puede usarse para establecer un título para la alerta
await pinguiAlert.send('¡Backup de base de datos completado con éxito! ✅', 'Trabajo Completado');

Casos de Uso

Aquí tienes algunos ejemplos claros de cómo aplicar Pingui Alert en escenarios reales, cumpliendo estrictamente con los Mandamientos.

try {
  await processPayment(orderId, amount);
} catch (error) {
  // ❌ MAL: Enviando el stack completo o PII del usuario
  // await client.send(`Payment failed for user ${user.email}: ${error.stack}`);

  // ✅ BIEN: Accionable, específico, seguro
  logger.error(error); // Loguear detalles localmente
  await client.send(
    `🚨 Crítico: Fallo en Pasarela de Pago\n` +
    `Pasarela: Stripe\n` +
    `OrderId: ${orderId}\n` +
    `Acción: Revisar Estado de Stripe y Logs inmediatamente.`
  );
}

#!/bin/bash
USAGE=$(df / | grep / | awk '{ print $5 }' | sed 's/%//g')

# Solo alertar si el uso es > 90% (Crítico)
if [ "$USAGE" -gt 90 ]; then
  curl -X POST https://pingui-alert.dev/api/alert \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "alert": "💾 Crítico: Disco del Servidor\nUso al '"$USAGE"'%.\nLimpiar logs o expandir volumen AHORA."
    }'
fi

if (failedAttempts > 10) {
  // Lógica de bloqueo de IP...

  // Alertar al Equipo de Seguridad
  await client.send(
    `🛡️ Alerta de Seguridad: Brute Force Detectado\n` +
    `IP: ${req.ip}\n` +
    `Intentos: ${failedAttempts}\n` +
    `Acción: IP baneada temporalmente. Verificar origen del tráfico.`
  );
}

job.on('failed', async (err) => {
  try {
    await client.send(
      `💥 Fallo en Job de Backup\n` +
      `Job: nightly_db_backup\n` +
      `Error: Connection timeout\n` +
      `Acción: Reintentar backup manualmente vía panel de admin.`
    );
  } catch (alertError) {
    // Fallar seguro - no crashear el worker si la alerta falla
    console.error('Failed to send alert:', alertError);
  }
});