Discord PortfolioBuildBytGithub
Page cover

Nebura

Nebura

Nebura es una plataforma API modular que integra múltiples servicios como Discord, WhatsApp, GitHub, Google AI y más. Este proyecto está diseñado para ser extensible, soportar comunicación en tiempo real y ofrecer monitoreo robusto, haciéndolo ideal para aplicaciones modernas multi-servicio.

Tabla de Contenidos

  • Descripción del Proyecto

  • Arquitectura

  • Módulos

    • Servidor API

    • Módulo Discord

    • Módulo WhatsApp

  • Configuración

  • Ejemplos de Uso

  • Desarrollo y Scripts

  • Contribuir

  • Soporte y Enlaces

  • Sobre el Creador

  • Resumen de la API

  • Estructura de Carpetas

Descripción del Proyecto

Nebura es una plataforma API modular basada en TypeScript que permite la integración fluida de diversos servicios. Utiliza Express, Socket.IO, Prisma ORM y otras librerías modernas para proporcionar un backend escalable y mantenible para bots, automatización y aplicaciones en tiempo real.

Características principales:

  • Arquitectura modular para Discord, WhatsApp y más.

  • Comunicación en tiempo real mediante WebSockets.

  • Registro, métricas y monitoreo robustos.

  • Respaldos automáticos y tareas programadas.

  • Soporte multilenguaje con i18next.

  • Gestión segura de sesiones y limitación de peticiones.

  • Sistema extensible de comandos y eventos para Discord.

Arquitectura

El núcleo de Nebura es orquestado por la clase Engine (src/main.ts), que inicializa y gestiona todos los módulos:

  • Servidor API (src/server/index.ts): Servidor HTTP basado en Express con Socket.IO, documentación Swagger, seguridad y métricas.

  • Módulo Discord (src/modules/discord/client.ts): Cliente avanzado de bot de Discord con carga dinámica de comandos, manejo de eventos y modularidad.

  • Módulo WhatsApp (src/modules/whatsapp/index.ts): Cliente WhatsApp Web.js con registro en Excel, reportes de estado y respaldos programados.

  • Base de datos: Gestionada mediante Prisma ORM, soportando upserts y consultas avanzadas.

  • Monitoreo: (Opcional) Integración con Sentry para seguimiento de errores.

Módulos

Servidor API

  • Archivo: src/server/index.ts

  • Stack: Express, Socket.IO, Swagger, Helmet, Apicache, i18next, gestión de sesiones.

  • Características:

    • Middleware para seguridad, caché, métricas y localización.

    • Swagger UI para documentación de la API.

    • Soporte WebSocket en tiempo real.

    • Servidor de archivos estáticos para documentación y recursos.

    • Bloqueo de IPs y limitación de peticiones.

    • Trazado de peticiones/respuestas con IDs únicos y tiempos de respuesta.

Ejemplo: Iniciar el Servidor API

import { API } from "./server";
const api = new API();
api.start();

Módulo Discord

  • Archivo: src/modules/discord/client.ts

  • Stack: discord.js, carga dinámica de comandos/eventos/componentes.

  • Características:

    • Estrategias avanzadas de caché y limpieza.

    • Carga y recarga dinámica de comandos, botones, modales y menús.

    • Gestión de alias y descubrimiento recursivo de archivos.

    • Gestión de emojis (servidor y fallback).

    • Manejo de errores y registro.

Ejemplo: Recargar un Comando

await client.reloadCommand("ping");

Ejemplo: Cargar Todos los Comandos

await client.loadCommands();

Módulo WhatsApp

  • Archivo: src/modules/whatsapp/index.ts

  • Stack: whatsapp-web.js, ExcelJS, qrcode-terminal.

  • Características:

    • Registra todos los mensajes entrantes en archivos Excel diarios.

    • Comando /status para estadísticas en tiempo real (uptime, mensajes no leídos, info de respaldos).

    • Respaldos diarios programados en Excel con estadísticas de chats.

    • Autenticación por código QR y gestión de sesiones.

    • Manejo robusto de errores y registro.

Ejemplo: Comando de Estado en WhatsApp

Envía /status desde el número propio del bot para recibir un reporte detallado de estado.

Configuración

La configuración se gestiona mediante variables de entorno y el objeto config.

  • Base de datos: Define DATABASE_URL en tu entorno.

  • Discord: Proporciona token, clientId, clientSecret y owners en la configuración.

  • WhatsApp: Habilita/deshabilita con modules.whatsapp.enabled.

  • Respaldos: Define CRON_BACKUPS_TIME para los respaldos programados.

  • Sentry: (Opcional) Configura Sentry DSN y entorno.

Consulta package.json para scripts y dependencias.

Ejemplos de Uso

Iniciar la Aplicación

npm install
npm run build
npm start

Modo Desarrollo

npm run start:dev

Lint y Formateo

npm run lint
npm run lint:fix
npm run type-check

Ejecutar Pruebas

npm test

Desarrollo y Scripts

  • Build: npm run build

  • Start: npm start

  • Modo Dev: npm run start:dev

  • Lint: npm run lint

  • Type Check: npm run type-check

  • Docs: npm run docs

  • Release: npm run release

  • Prepare: npm run prepare (husky hooks)

Consulta todos los scripts en package.json.

Contribuir

¡Las contribuciones son bienvenidas! Por favor abre issues o pull requests en GitHub.

Soporte y Enlaces

Sobre el Creador

Nebura es desarrollado y mantenido por Hiroshi025.

"Mi misión es construir plataformas robustas, escalables y modulares que permitan a los desarrolladores integrar y automatizar múltiples servicios con facilidad. Si tienes preguntas, sugerencias o quieres contribuir, no dudes en contactarme por GitHub o el centro de ayuda."

Resumen de la API

La API de Nebura expone endpoints RESTful para gestión de tareas, recordatorios, licencias, bloqueo de IPs, integración con Discord, Google Gemini y más.

Autenticación

La mayoría de los endpoints requieren autenticación mediante un token Bearer JWT. Incluye el token en el header Authorization:

Authorization: Bearer tu.jwt.token.aqui

Algunos endpoints públicos (por ejemplo, /public/github/users/{username}) no requieren autenticación.

Endpoints Principales

Tareas y Recordatorios

  • GET /service/tasks: Lista todas las tareas, permite filtrar por estado, prioridad, creador o etiqueta.

  • POST /service/tasks: Crea una nueva tarea.

  • GET /service/tasks/{id}: Obtiene detalles de una tarea.

  • PATCH /service/tasks/{id}: Actualiza campos de una tarea.

  • DELETE /service/tasks/{id}: Elimina una tarea.

  • GET /service/reminders: Lista los recordatorios próximos a activarse.

Licencias

  • POST /license: Crea una nueva licencia (requiere admin).

  • GET /license: Lista todas las licencias.

  • GET /license/{id}: Detalles de una licencia.

  • PUT /license/{id}: Actualiza una licencia.

  • DELETE /license/{id}: Elimina una licencia.

  • POST /license/validate/{key}: Valida una licencia contra un HWID.

  • GET /license/info/{licenseKey}: Información detallada de una licencia, IPs bloqueadas y estadísticas de uso.

Seguridad y Administración

  • POST /admin/block-ip: Bloquea una IP.

  • DELETE /admin/unblock-ip/{ipAddress}: Desbloquea una IP.

  • GET /admin/blocked-ips: Lista IPs bloqueadas.

  • GET /admin/ip-info/{ipAddress}: Información de seguridad de una IP.

  • GET /admin/cache-performance: Métricas de caché (solo desarrollo).

  • GET /admin/prisma-metrics: Métricas recientes de Prisma (solo admin).

Integraciones

GitHub

  • GET /public/github/users/{username}: Info básica de usuario.

  • GET /public/github/users/{username}/all: Info completa (repos, eventos, orgs).

  • GET /public/github/users/{username}/repos: Repositorios públicos.

  • GET /public/github/repos/{owner}/{repo}: Info de un repositorio.

Discord

  • GET /public/discord/status: Estado actual de Discord.

  • GET /public/discord/updates: Últimas novedades de Discord.

  • GET /public/discord/incidents: Incidentes activos.

  • GET /publicdiscord/recent: Estado, novedades e incidentes recientes.

Google Gemini

  • POST /service/google/model-ai/text: Procesa texto con Gemini.

  • POST /service/google/model-ai/file: Procesa archivo con Gemini.

  • POST /service/google/model-ai/combined: Procesa texto y archivo juntos.

Autenticación de Usuarios

  • POST /auth/register: Registro de usuario y generación de JWT.

  • POST /auth/login: Login y obtención de JWT.

  • GET /auth/{id}: Datos del usuario autenticado.

Ejemplo de Uso de la API

Crear una Tarea

curl -X POST https://host.hiroshi-dev.me/api/v1/service/tasks \
  -H "Authorization: Bearer tu.jwt.token.aqui" \
  -H "Content-Type: application/json" \
  -d '{"title":"Reunión mensual","createdBy":"usuario123"}'

Validar una Licencia

curl -X POST https://host.hiroshi-dev.me/api/v1/license/validate/CLAVE-LICENCIA \
  -d "hwid=HWID12345"

Obtener Estado del Sistema

curl https://host.hiroshi-dev.me/api/v1/public/status

Esquemas de Respuesta

Las respuestas siguen los esquemas definidos en la documentación Swagger. Por ejemplo, una tarea (TaskResponse) incluye:

{
  "id": "507f1f77bcf86cd799439011",
  "title": "Reunión mensual",
  "description": "Discutir presupuesto",
  "createdBy": "usuario123",
  "createdAt": "2024-01-20T10:00:00Z",
  "status": "pending",
  "priority": "high",
  "tags": ["trabajo", "finanzas"],
  "reminder": { "enabled": true, "timeBefore": "30 minutes", "notified": false },
  "recurrence": { "type": "monthly", "interval": 1 },
  "autoDelete": "2024-12-31T23:59:59Z"
}

Documentación Interactiva

  • Accede a la documentación Swagger UI en: http://localhost:PORT/docs (después de iniciar el servidor)

  • Consulta la documentación oficial para guías y ejemplos detallados.

Licencia

Este proyecto está licenciado bajo la Licencia ISC. Consulta el archivo LICENSE para más detalles.

Estructura de Carpetas

La siguiente estructura muestra la organización principal del proyecto. Cada carpeta tiene una responsabilidad clara para facilitar el mantenimiento y la escalabilidad.

src/
├── adapters/           # Adaptadores para base de datos, servicios externos y validadores
│   ├── database/       # Prisma ORM y archivos de sesión
│   ├── external/       # Integraciones externas (GitHub, Passport, Swagger)
│   └── validators/     # Validadores de datos (licencia, tareas, usuario)
├── application/        # Lógica de negocio, DTOs, entidades y servicios
│   ├── dto/            # Objetos de transferencia de datos (DTOs)
│   ├── entities/       # Entidades de dominio
│   └── services/       # Servicios de aplicación (auth, licencia, utilidades)
├── gateaway/           # Repositorios para acceso a datos (auth, licencia, tareas)
├── interfaces/         # Interfaces HTTP: controladores, middlewares, rutas y vistas
│   ├── http/
│   │   ├── controllers/    # Controladores organizados por dominio
│   │   ├── middlewares/    # Middlewares de autenticación, tokens, web
│   │   ├── routes/         # Definición de rutas API/web
│   │   └── views/          # Vistas EJS, CSS, imágenes y scripts públicos
│   └── messaging/      # Mensajería y módulos para Discord, WhatsApp, etc.
├── locales/            # Archivos de localización (i18n) por idioma
├── shared/             # Código compartido: clases utilitarias, funciones, constantes
├── typings/            # Definiciones TypeScript personalizadas
├── index.ts            # Punto de entrada principal
├── main.ts             # Inicialización del motor principal

Descripción de carpetas principales:

  • adapters/: Contiene adaptadores para la base de datos (Prisma), integraciones externas (como GitHub o Passport) y validadores de datos.

  • application/: Incluye la lógica de negocio, entidades, DTOs y servicios principales de la aplicación.

  • gateaway/: Repositorios que gestionan el acceso y persistencia de datos para dominios como autenticación, licencias y tareas.

  • interfaces/: Define las interfaces HTTP (controladores, middlewares, rutas, vistas) y módulos de mensajería (bots de Discord, WhatsApp, etc.).

  • locales/: Archivos de internacionalización y localización para soportar múltiples idiomas.

  • shared/: Código y utilidades compartidas entre distintos módulos del proyecto.

  • typings/: Definiciones de tipos TypeScript personalizadas para el proyecto.

  • index.ts / main.ts: Archivos de entrada y bootstrap del motor principal de la plataforma.

Notas:

  • Los módulos de bots (Discord, WhatsApp) están bajo src/interfaces/messaging/modules/.

  • Las vistas y recursos estáticos se encuentran en src/interfaces/http/views/public/.

  • Los servicios de negocio y utilidades están en src/application/services/ y src/shared/.

PreviousBienvenidoNextModulos

Last updated