blackcoffee2 2.1.0

package/docs/EVENTS_APP_MANUAL.md

@@ -0,0 +1,289 @@
+# ☕ events-app - Aplicación de Eventos BlackCoffee
+
+## Descripción General
+
+**events-app** es una aplicación BlackCoffee que consulta la tabla `events_no_finish` de la base de datos `otrack_db` en MariaDB/MySQL.
+
+**Versión:** 1.0.0  
+**Pool de Base de Datos:** MySQL-MariaDB  
+**Tabla Principal:** events_no_finish
+
+---
+
+## 📁 Estructura de la Aplicación
+
+```
+apps/events-app/1.0.0/
+├── package.json                 # Manifest con configuración BlackCoffee
+├── controllers/
+│   └── EventsController.js      # Controlador con 6 endpoints API
+├── models/
+│   └── EventsModel.js           # Modelo con consultas a events_no_finish
+├── views/
+│   └── index.html               # UI Web con tabla de eventos
+├── routes/
+│   └── api.json                 # 7 rutas definidas
+└── public/assets/
+    ├── css/styles.css
+    └── js/
+```
+
+---
+
+## 🗄️ Configuración del Pool
+
+La aplicación utiliza el pool **`MySQL-MariaDB`** configurado en `config/database.json`:
+
+```json
+{
+  "MySQL-MariaDB": {
+    "type": "mariadb",
+    "host": "localhost",
+    "port": 3306,
+    "user": "root",
+    "password": "",
+    "database": "otrack_db",
+    "connectionLimit": 10
+  }
+}
+```
+
+---
+
+## 📡 Endpoints API
+
+| Método | Endpoint | Descripción | Parámetros |
+|--------|----------|-------------|------------|
+| GET | `/events-app/1.0.0/` | Página principal | - |
+| GET | `/events-app/1.0.0/api/events` | Listar eventos | `limit`, `offset`, `order` |
+| GET | `/events-app/1.0.0/api/events/:id` | Obtener evento por ID | `id` |
+| GET | `/events-app/1.0.0/api/events/type/:type` | Buscar por tipo | `type` |
+| GET | `/events-app/1.0.0/api/events/session/:sessionId` | Buscar por session_id | `sessionId` |
+| GET | `/events-app/1.0.0/api/events/stats` | Estadísticas | - |
+
+---
+
+## 📊 Estructura de la Tabla events_no_finish
+
+```sql
+CREATE TABLE events_no_finish (
+  id                bigint(20) unsigned  NOT NULL AUTO_INCREMENT,
+  session_header_id bigint(20) unsigned  NOT NULL,
+  event_type        varchar(50)          NOT NULL,
+  created_at        datetime             DEFAULT CURRENT_TIMESTAMP,
+  qty               int(11)              DEFAULT NULL,
+  product_id        bigint(20)           DEFAULT NULL,
+  sku               varchar(100)         DEFAULT NULL,
+  product_name      text                 DEFAULT NULL,
+  url               varchar(1000)        DEFAULT NULL,
+  price             text                 DEFAULT NULL,
+  old_qty           bigint(20)           DEFAULT NULL,
+  new_qty           bigint(20)           DEFAULT NULL,
+  compressed_data   text                 DEFAULT NULL,
+  data_hash         varchar(100)         DEFAULT NULL,
+  event_timestamp   timestamp            DEFAULT NULL,
+  session_id        varchar(255)         DEFAULT NULL,
+  wtf_session       varchar(255)         DEFAULT NULL,
+  site_url          varchar(500)         DEFAULT NULL,
+  PRIMARY KEY (id)
+);
+```
+
+---
+
+## 🔧 Características Técnicas
+
+### 1. Serialización de Datos
+- **BigInt → String**: Los valores `bigint` de MariaDB se convierten automáticamente a string
+- **Date → ISO String**: Las fechas se serializan en formato ISO 8601
+
+### 2. Lazy Loading del Modelo
+El modelo se inicializa bajo demanda cuando se realiza la primera consulta:
+```javascript
+async getEventsModel() {
+  if (this.eventsModel) return this.eventsModel;
+  // Inicialización bajo demanda
+}
+```
+
+### 3. Hot Reload Compatible
+La aplicación es detectada automáticamente por el Hot Reload Manager:
+- Detección de nuevas apps en `apps/{name}/{version}/`
+- Recarga automática de rutas al modificar archivos
+- Watch continuo para cambios futuros
+
+---
+
+## 📝 Ejemplos de Uso
+
+### Listar Eventos
+```bash
+curl -k "https://localhost:9791/events-app/1.0.0/api/events?limit=10"
+```
+
+**Respuesta:**
+```json
+{
+  "success": true,
+  "pool": "MySQL-MariaDB",
+  "table": "events_no_finish",
+  "count": 10,
+  "total": 11,
+  "data": [
+    {
+      "id": "17",
+      "session_header_id": "12345",
+      "event_type": "view_product",
+      "created_at": "2026-02-04T23:09:40.000Z",
+      "session_id": "30f08519743a83f22ad4bf7b866cda43",
+      "product_name": "Producto Ejemplo"
+    }
+  ],
+  "timestamp": "2026-02-17T19:45:00.000Z"
+}
+```
+
+### Obtener Evento por ID
+```bash
+curl -k "https://localhost:9791/events-app/1.0.0/api/events/17"
+```
+
+### Buscar por Tipo de Evento
+```bash
+curl -k "https://localhost:9791/events-app/1.0.0/api/events/type/view_product"
+```
+
+### Buscar por Session ID
+```bash
+curl -k "https://localhost:9791/events-app/1.0.0/api/events/session/30f08519743a83f22ad4bf7b866cda43"
+```
+
+### Obtener Estadísticas
+```bash
+curl -k "https://localhost:9791/events-app/1.0.0/api/events/stats"
+```
+
+**Respuesta:**
+```json
+{
+  "success": true,
+  "pool": "MySQL-MariaDB",
+  "data": {
+    "total": 11,
+    "byType": [
+      { "event_type": "view_product", "count": 5 },
+      { "event_type": "add_to_cart", "count": 4 },
+      { "event_type": "remove_from_cart", "count": 2 }
+    ],
+    "bySession": [...]
+  },
+  "timestamp": "2026-02-17T19:45:00.000Z"
+}
+```
+
+---
+
+## 🎯 UI Web
+
+La aplicación incluye una interfaz web accesible en:
+```
+https://localhost:9791/events-app/1.0.0/
+```
+
+**Características de la UI:**
+- Tabla de eventos con paginación
+- Filtros por tipo de evento
+- Búsqueda por session_id
+- Estadísticas en tiempo real
+- Diseño responsive con tema oscuro
+- Actualización automática con botón refresh
+
+---
+
+## 📦 Manifest (package.json)
+
+```json
+{
+  "name": "events-app",
+  "version": "1.0.0",
+  "description": "Aplicación para consultar eventos no finalizados de otrack_db",
+  "author": "BlackCoffee Team",
+  "blackcoffee": {
+    "displayName": "Events App",
+    "entryPoint": "routes/api.json",
+    "autoStart": true,
+    "minBlackCoffeeVersion": "2.0.0",
+    "database": {
+      "pool": "MySQL-MariaDB",
+      "models": ["EventsModel"]
+    }
+  }
+}
+```
+
+---
+
+## 🔗 URLs de Acceso
+
+| Recurso | URL |
+|---------|-----|
+| UI Web | `https://localhost:9791/events-app/1.0.0/` |
+| API Events | `https://localhost:9791/events-app/1.0.0/api/events` |
+| API Stats | `https://localhost:9791/events-app/1.0.0/api/events/stats` |
+
+---
+
+## 🛠️ Desarrollo
+
+### Agregar Nuevo Endpoint
+
+1. **Agregar método en EventsModel.js:**
+```javascript
+async findByDate(date) {
+  const selectSQL = `
+    SELECT * FROM ${this.tableName}
+    WHERE DATE(created_at) = ?
+    ORDER BY id DESC
+  `;
+  return await this.adapter.query(selectSQL, [date]);
+}
+```
+
+2. **Agregar método en EventsController.js:**
+```javascript
+async getEventsByDate(req, res) {
+  const model = await this.getEventsModel();
+  const date = req.params?.date;
+  const events = await model.findByDate(date);
+  
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({
+    success: true,
+    count: events.length,
+    data: serializeBigInt(events),
+    timestamp: new Date().toISOString()
+  }));
+}
+```
+
+3. **Agregar ruta en routes/api.json:**
+```json
+{
+  "method": "GET",
+  "path": "/api/events/date/:date",
+  "handler": "getEventsByDate",
+  "controller": "controllers/EventsController.js"
+}
+```
+
+---
+
+## 📄 Licencia
+
+Apache License 2.0 - BlackCoffee Project
+
+---
+
+**Documento creado:** 2026-02-17  
+**BlackCoffee:** v2.0.0  
+**events-app:** v1.0.0

package/docs/INSITU_BINARY_UPLOAD_PROPOSAL.md

@@ -0,0 +1,186 @@
+# Propuesta para Insitu Framework - Binary Upload Support
+
+## 📋 Resumen
+
+BlackCoffee App Server requiere soporte nativo para **binary uploads** (archivos .tar.gz, imágenes, etc.). Actualmente, Insitu Framework convierte todo el body a string UTF-8, lo que corrompe archivos binarios.
+
+## 🐛 Problema Actual
+
+En `lib/core/server.js`, línea ~989:
+
+```javascript
+// CÓDIGO ACTUAL DE INSITU
+req.body = Buffer.concat(bodyChunks).toString();
+```
+
+**Problema:** `.toString()` convierte el buffer a string UTF-8, corrompiendo datos binarios.
+
+**Síntomas:**
+- Archivos .tar.gz llegan corruptos (1720 bytes → 1637 bytes)
+- Magic number gzip (0x1f 0x8b) se pierde
+- Imágenes y otros binarios no se pueden subir
+
+## ✅ Solución Propuesta
+
+Agregar `req.rawBody` como Buffer **antes** de convertir a string:
+
+```javascript
+// PROPUESTA PARA INSITU
+const rawBuffer = Buffer.concat(bodyChunks);
+
+// Binary Upload Support - BlackCoffee
+req.rawBody = rawBuffer;  // ← NUEVO: Body raw como Buffer
+
+// Comportamiento original - string para req.body
+req.body = rawBuffer.toString();
+
+// Parsear body si es JSON (sin cambios)
+if (this.isJsonRequest(req)) {
+  try {
+    req.body = JSON.parse(req.body);
+  } catch (e) {
+    req.body = {};
+  }
+}
+```
+
+## 📊 Beneficios para Insitu
+
+1. **Backward Compatible** - `req.body` sigue funcionando igual
+2. **Binary Upload Support** - `req.rawBody` disponible para archivos
+3. **Sin Breaking Changes** - Todo el código existente sigue funcionando
+4. **Habilita casos de uso avanzados:**
+   - Upload de imágenes
+   - Upload de archivos .tar.gz
+   - Upload de PDFs, documentos
+   - Cualquier archivo binario
+
+## 🔧 Ubicación del Cambio
+
+**Archivo:** `lib/core/server.js`  
+**Función:** `handleRequest(req, res)`  
+**Línea:** ~989 (dentro de `req.on('end', async () => {...})`)
+
+## 📝 Código Completo Propuesto
+
+```javascript
+req.on('end', async () => {
+  try {
+    // Concatenar todos los chunks una sola vez
+    const rawBuffer = Buffer.concat(bodyChunks);
+    
+    // ============================================
+    // BINARY UPLOAD SUPPORT
+    // ============================================
+    // Guardar body raw como Buffer para rutas binarias
+    // Esto permite uploads de archivos binarios (.tar.gz, imágenes, etc.)
+    req.rawBody = rawBuffer;
+    // ============================================
+    
+    // Convertir a string para req.body (comportamiento original)
+    req.body = rawBuffer.toString();
+
+    // Actualizar estadísticas globales de bytes recibidos
+    StatsHooksHandler.updateRequestBytes(bodySize);
+
+    // Parsear body si es JSON
+    if (this.isJsonRequest(req)) {
+      try {
+        req.body = JSON.parse(req.body);
+      } catch (e) {
+        req.body = {};
+
+        if (hooks) {
+          hooks.doAction('request_body_parse_error', req, res, e);
+        }
+      }
+    }
+    
+    // ... resto del código sin cambios ...
+```
+
+## 🧪 Casos de Prueba
+
+### 1. JSON Upload (Existente - Sin Cambios)
+```javascript
+// POST /api/users con Content-Type: application/json
+// req.body = { name: "John", email: "john@example.com" }
+// req.rawBody = <Buffer 7b 22 6e 61 6d 65 22 ...>
+```
+
+### 2. Binary Upload (Nuevo)
+```javascript
+// POST /api/admin/apps/deploy con archivo .tar.gz
+// req.body = " (string corrupto)
+// req.rawBody = <Buffer 1f 8b 08 00 ...> ← Buffer binario correcto
+```
+
+### 3. Multipart Form-Data (Navegador)
+```javascript
+// POST desde <input type="file">
+// Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
+// req.rawBody = <Buffer completo con multipart>
+// req.body = " (string)
+```
+
+## 📁 Archivos Modificados en BlackCoffee
+
+BlackCoffee ya implementó esta solución en:
+
+**Archivo:** `node_modules/insitu-js/lib/core/server.js`  
+**Líneas:** 991-1001
+
+```javascript
+// Línea 991-1001
+const rawBuffer = Buffer.concat(bodyChunks);
+
+// ============================================
+// BINARY UPLOAD SUPPORT - BlackCoffee
+// ============================================
+// Guardar body raw como Buffer para rutas binarias
+// Esto permite uploads de archivos binarios (.tar.gz, imágenes, etc.)
+req.rawBody = rawBuffer;
+// ============================================
+
+// Convertir a string para req.body (comportamiento original)
+req.body = rawBuffer.toString();
+```
+
+## ✅ Estado Actual
+
+**BlackCoffee v2.0.0:**
+- ✅ Binary Upload Support implementado
+- ✅ Multipart/form-data parser para uploads desde navegador
+- ✅ Deploy de aplicaciones desde UI Web funcional
+- ✅ req.rawBody disponible en todos los handlers
+
+**Insitu Framework v1.3.0:**
+- ✅ Binary Upload Support incorporado en el core
+- ✅ Firewall exception para deploy incorporada
+- ✅ Nuestras propuestas fueron aceptadas e implementadas
+
+## 🎉 Propuestas Aceptadas
+
+Las siguientes características propuestas por BlackCoffee fueron incorporadas en Insitu Framework v1.3.0:
+
+1. **req.rawBody** - Binary Upload Support (línea 997 de `lib/core/server.js`)
+2. **Firewall Exception** - Excepción para `/api/admin/apps/deploy` (líneas 403-406 de `lib/middleware/firewall.js`)
+
+**¡Gracias al equipo de Insitu por escuchar a la comunidad!** 🙌
+
+## 📞 Contacto
+
+**BlackCoffee Team:**
+- Repository: https://gitlab.com/bytedogssyndicate1/bc2
+- Author: Benjamin Sanchez Cardenas
+- Email: bytedogssyndicate@gmail.com
+
+**Insitu Framework:**
+- Repository: https://github.com/insitu-framework/insitu-js
+- npm: https://www.npmjs.com/package/insitu-js
+
+---
+
+**Documento creado:** 2026-02-17  
+**BlackCoffee:** v2.0.0  
+**Insitu Framework:** v1.2.1 (modificado localmente)

package/docs/INSITU_FIREWALL_EXCEPTION.md

@@ -0,0 +1,187 @@
+# Cambios en Insitu Framework para BlackCoffee
+
+## 📋 Resumen
+
+BlackCoffee App Server requirió dos modificaciones al core de Insitu Framework para habilitar:
+1. **Binary Upload Support** (req.rawBody)
+2. **Firewall Exception** para deploy de aplicaciones
+
+---
+
+## 🔧 Cambio 1: Binary Upload Support
+
+### Archivo: `lib/core/server.js`
+
+**Ubicación:** Función `handleRequest(req, res)`, línea ~991
+
+### Código Original
+```javascript
+// Línea ~989
+req.body = Buffer.concat(bodyChunks).toString();
+```
+
+### Código Modificado
+```javascript
+// Líneas 991-1001
+const rawBuffer = Buffer.concat(bodyChunks);
+
+// ============================================
+// BINARY UPLOAD SUPPORT - BlackCoffee
+// ============================================
+// Guardar body raw como Buffer para rutas binarias
+// Esto permite uploads de archivos binarios (.tar.gz, imágenes, etc.)
+req.rawBody = rawBuffer;
+// ============================================
+
+// Convertir a string para req.body (comportamiento original)
+req.body = rawBuffer.toString();
+```
+
+### Beneficios
+- ✅ Backward compatible - `req.body` sigue funcionando igual
+- ✅ Binary upload support - `req.rawBody` disponible como Buffer
+- ✅ Sin breaking changes - Todo el código existente funciona
+- ✅ Habilita uploads de archivos binarios
+
+---
+
+## 🔧 Cambio 2: Firewall Exception para Deploy
+
+### Archivo: `lib/middleware/firewall.js`
+
+**Ubicación:** Función `middleware()`, línea 401
+
+### Código Original
+```javascript
+// Línea ~401
+middleware() {
+  return (req, res, next) => {
+    // Disparar hook antes de procesar la solicitud
+    const hooks = require('../../index.js').hooks;
+    if (hooks) {
+      hooks.doAction('firewall_request_received', req, res);
+    }
+    // ... resto del middleware
+```
+
+### Código Modificado
+```javascript
+// Líneas 401-407
+middleware() {
+  return (req, res, next) => {
+    // Excluir rutas de administración de deploy
+    if (req.method === 'POST' && req.url.startsWith('/api/admin/apps/deploy')) {
+      return next(); // Saltar firewall para deploy
+    }
+
+    // Disparar hook antes de procesar la solicitud
+    const hooks = require('../../index.js').hooks;
+    if (hooks) {
+      hooks.doAction('firewall_request_received', req, res);
+    }
+    // ... resto del middleware
+```
+
+### Beneficios
+- ✅ Permite deploy de aplicaciones sin desactivar WAF completamente
+- ✅ Excepción específica para `/api/admin/apps/deploy`
+- ✅ El WAF sigue activo para todas las demás rutas
+- ✅ Previene falsos positivos con archivos .tar.gz
+
+---
+
+## 📊 Estado Actual
+
+| Archivo | Estado | Cambios |
+|---------|--------|---------|
+| `lib/core/server.js` | ✅ Modificado | req.rawBody como Buffer |
+| `lib/middleware/firewall.js` | ✅ Modificado | Excepción para deploy |
+
+---
+
+## 🚀 Propuesta para Insitu v1.3.0
+
+### 1. Incorporar Binary Upload Support
+
+**Ventajas:**
+- Habilita casos de uso de file upload
+- Compatible con todas las apps existentes
+- Sin cambios en la API pública
+
+**Implementación Sugerida:**
+```javascript
+// lib/core/server.js, línea ~991
+const rawBuffer = Buffer.concat(bodyChunks);
+
+// Binary Upload Support
+req.rawBody = rawBuffer;  // ← NUEVO
+
+// Comportamiento original
+req.body = rawBuffer.toString();
+```
+
+### 2. Incorporar Firewall Exceptions
+
+**Ventajas:**
+- Permite configurar rutas excluidas del WAF
+- Útil para uploads de archivos grandes
+- Previene falsos positivos
+
+**Implementación Sugerida:**
+```javascript
+// lib/middleware/firewall.js, constructor
+constructor(options = {}) {
+  this.excludedRoutes = options.excludedRoutes || [];
+  // ... resto del constructor
+}
+
+// lib/middleware/firewall.js, middleware()
+middleware() {
+  return (req, res, next) => {
+    // Verificar rutas excluidas
+    if (this.excludedRoutes.some(route => req.url.startsWith(route))) {
+      return next();
+    }
+    
+    // ... resto del middleware
+  }
+}
+```
+
+**Configuración:**
+```javascript
+const firewall = new Firewall({
+  excludedRoutes: ['/api/admin/apps/deploy']
+});
+```
+
+---
+
+## 📁 Archivos de Referencia
+
+BlackCoffee mantiene estos cambios en:
+- `node_modules/insitu-js/lib/core/server.js`
+- `node_modules/insitu-js/lib/middleware/firewall.js`
+
+**Documentación completa en:**
+- `docs/INSITU_BINARY_UPLOAD_PROPOSAL.md` - Propuesta detallada
+- `docs/INSITU_FIREWALL_EXCEPTION.md` - Este archivo
+
+---
+
+## 📞 Contacto
+
+**BlackCoffee Team:**
+- Repository: https://gitlab.com/bytedogssyndicate1/bc2
+- Author: Benjamin Sanchez Cardenas
+- Email: bytedogssyndicate@gmail.com
+
+**Insitu Framework:**
+- Repository: https://github.com/insitu-framework/insitu-js
+- npm: https://www.npmjs.com/package/insitu-js
+
+---
+
+**Documento creado:** 2026-02-17  
+**BlackCoffee:** v2.0.0  
+**Insitu Framework:** v1.2.1 (modificado localmente)