@jmlq/logger 0.1.0-alpha.2 → 0.1.0-alpha.20

package/README.md

@@ -0,0 +1,247 @@
+# @jmlq/logger
+
+Sistema de logging modular y extensible con **Arquitectura Limpia**. Soporta múltiples destinos (archivos, MongoDB, PostgreSQL) y enmascarado automático de datos sensibles (PII).
+
+## 📦 Instalación
+
+```bash
+# Core del logger
+npm install @jmlq/logger
+
+# Plugins opcionales (instala según necesites)
+npm install @jmlq/logger-plugin-fs        # Para archivos
+npm install @jmlq/logger-plugin-mongo     # Para MongoDB
+npm install @jmlq/logger-plugin-postgresql # Para PostgreSQL
+```
+
+## 🚀 Uso Básico
+
+Con esta configuración se busca:
+
+- Tener un **logger centralizado** basado en `@jmlq/logger`.
+- Enviar logs a uno o varios de estos destinos (**opcionales** y combinables):
+  - Sistema de archivos (`@jmlq/logger-plugin-fs`)
+  - MongoDB (`@jmlq/logger-plugin-mongo`)
+  - PostgreSQL (`@jmlq/logger-plugin-postgresql`)
+- Integrar el logger con:
+  - Express (por request) mediante un middleware (`req.logger` + `req.requestId`).
+  - El ciclo de vida de la app: arranque, apagado limpio y fallos no controlados.
+
+---
+
+## 🎯 Características Principales
+
+### Niveles de Log
+
+- `TRACE` (10) - Información muy detallada
+- `DEBUG` (20) - Información de depuración
+- `INFO` (30) - Información general
+- `WARN` (40) - Advertencias
+- `ERROR` (50) - Errores
+- `FATAL` (60) - Errores críticos
+
+### Enmascarado PII Automático
+
+El logger detecta y enmascara automáticamente datos sensibles utilizando patrones personalizados:
+
+```js
+
+      patterns: [
+      // Tarjetas de crédito
+      {
+        pattern: "\\b\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}\\b",
+        replaceWith: "****-****-****-****",
+      },
+      // Números de cuenta bancaria
+      {
+        pattern: "\\b\\d{10,20}\\b",
+        replaceWith: "****ACCOUNT****",
+      },
+      // Tokens JWT
+      {
+        pattern: "eyJ[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*",
+        replaceWith: "****JWT****",
+      },
+    ],
+
+```
+
+Por ejemplo se tiene la siguiente información:
+
+```js
+[
+  {
+    id: "1",
+    name: "John Doe",
+    email: "john.doe@example.com",
+    card: "1234-5678-9012-3456",
+  },
+  {
+    id: "2",
+    name: "Jane Doe",
+    email: "jane.doe@example.com",
+    card: "6258-3842-9524-3251",
+  },
+];
+```
+
+Los logs registrarán lo siguiente:
+
+> - **File .log** (`@jmlq/logger-plugin-fs`)
+
+```js
+{
+  "level": 30,
+  "message": "Users listed successfully",
+  "meta": {
+    "count": 2,
+    "result": [
+      {
+        "id": "1",
+        "name": "John Doe",
+        "email": "***@***",
+        "card": "****-****-****-****"
+      },
+      {
+        "id": "2",
+        "name": "Jane Doe",
+        "email": "***@***",
+        "card": "****-****-****-****"
+      }
+    ]
+  },
+  "timestamp": 1765400661565,
+  "_id": "6939e0556925736129e1008d"
+}
+```
+
+> - **MongoDB** (`@jmlq/logger-plugin-mongo`)
+
+![MongoDB log](./assets/mongo-log.png)
+
+> - **MongoDB** (`@jmlq/logger-plugin-mongo`)
+
+![Postgresql log](./assets/pg-log.png)
+
+### Filtros y Consultas
+
+#### 1. Obtener todos los logs de nivel WARN o superior (en este caso retorna WARN, ERROR y FATAL)
+
+```ts
+const errors = await _req.logger?.getLogs({
+  levelMin: parseLogLevel("WARN"),
+});
+```
+
+Resultado:
+
+```ini
+[2025-12-10T21:19:58.804Z] [50] app.error {"name":"AppError","code":"INTERNAL","message":"Unhandled exception","retryable":false,"meta":null,"cause":{"cause":{}},"stack":"AppError: Unhandled exception\n    at AppError.internal (D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\shared\\errors\\app-error.js:61:16)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\presentation\\middlewares\\http\\error.middleware.js:36:40\n    at Layer.handleError (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\lib\\layer.js:116:17)\n
+   at trimPrefix (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:340:13)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:297:9\n    at processParams (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:582:12)\n    at Immediate.next (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:291:5)\n    at Immediate._onImmediate (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:688:15)\n    at process.processImmediate (node:internal/timers:485:21)"}
+[2025-12-10T21:19:58.804Z] [50] app.error {"code":"INTERNAL","name":"AppError","cause":{"cause":{}},"stack":"AppError: Unhandled exception\n    at AppError.internal (D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\shared\\errors\\app-error.js:61:16)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\presentation\\middlewares\\http\\error.middleware.js:36:40\n    at Layer.handleError (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\lib\\layer.js:116:17)\n    at trimPrefix (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:340:13)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:297:9\n    at processParams (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:582:12)\n    at Immediate.next (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:291:5)\n    at Immediate._onImmediate (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:688:15)\n    at process.processImmediate (node:internal/timers:485:21)","message":"Unhandled exception","retryable":false}
+
+```
+
+**NOTA**: `parseLogLevel` es un helper para convertir un `string` a `LogLevel`.
+
+#### 2. Filtrar por rango de fechas
+
+```ts
+const yesterday = Date.now() - 24 * 60 * 60 * 1000;
+const recentLogs = await _req.logger?.getLogs({
+  since: yesterday,
+  until: Date.now(),
+});
+```
+
+Resultado:
+
+```ini
+[2025-12-10T22:21:58.500Z] [30] app.shutdown.begin {"reason":"SIGINT"}
+[2025-12-10T21:12:59.216Z] [50] app.error {"name":"AppError","code":"INTERNAL","message":"Unhandled exception","retryable":false,"meta":null,"cause":{"cause":{}},"stack":"AppError: Unhandled exception\n    at AppError.internal (D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\shared\\errors\\app-error.js:61:16)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\presentation\\middlewares\\http\\error.middleware.js:36:40\n    at Layer.handleError (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\lib\\layer.js:116:17)\n    at trimPrefix (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:340:13)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:297:9\n    at processParams (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:582:12)\n    at Immediate.next (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:291:5)\n    at Immediate._onImmediate (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:688:15)\n    at process.processImmediate (node:internal/timers:485:21)"}
+[2025-12-10T21:04:21.565Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","name":"John Doe","email":"***@***","card":"****-****-****-****"},{"id":"2","name":"Jane Doe","email":"***@***","card":"****-****-****-****"}]}
+[2025-12-10T21:04:21.565Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","card":"****-****-****-****","name":"John Doe","email":"***@***"},{"id":"2","card":"****-****-****-****","name":"Jane Doe","email":"***@***"}]}
+[2025-12-10T21:03:32.910Z] [30] http.start {"host":"127.0.0.1","port":3000}
+```
+
+#### 3. Búsqueda por texto (en el campo mensaje del log)
+
+```ts
+const userLogs = await _req.logger?.getLogs({
+  query: "Users",
+});
+```
+
+Resultado:
+
+```ini
+[2025-12-10T22:58:09.874Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","card":"****-****-****-****","name":"John Doe","email":"***@***"},{"id":"2","card":"****-****-****-****","name":"Jane Doe","email":"***@***"}]}
+[2025-12-10T22:57:28.483Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","name":"John Doe","email":"***@***","card":"****-****-****-****"},{"id":"2","name":"Jane Doe","email":"***@***","card":"****-****-****-****"}]}
+```
+
+#### 4. Combinación de filtros
+
+```ts
+const logs = await _req.logger?.getLogs({
+  levelMin: parseLogLevel("INFO"),
+  since: Date.now() - 2 * 60 * 60 * 1000, // Últimas 2 horas
+  query: "successfully",
+});
+```
+
+Resultado:
+
+```ini
+[2025-12-10T23:05:31.791Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","name":"John Doe","email":"***@***","card":"****-****-****-****"},{"id":"2","name":"Jane Doe","email":"***@***","card":"****-****-****-****"}]}
+[2025-12-10T23:05:31.791Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","card":"****-****-****-****","name":"John Doe","email":"***@***"},{"id":"2","card":"****-****-****-****","name":"Jane Doe","email":"***@***"}]}
+[2025-12-10T22:58:09.874Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","name":"John Doe","email":"***@***","card":"****-****-****-****"},{"id":"2","name":"Jane Doe","email":"***@***","card":"****-****-****-****"}]}
+```
+
+## 🏗️ Arquitectura
+
+El paquete sigue **Arquitectura Limpia**:
+
+```
+src/
+├─ domain/           # Reglas de negocio puras
+│  ├─ entities/
+│  ├─ value-objects/ # LogLevel
+│  ├─ services/      # PiiRedactor, MessageNormalizer
+│  ├─ ports/         # Interfaces/contratos
+│  └─ types/
+├─ application/      # Casos de uso
+│  ├─ use-cases/     # SaveLog, GetLogs, FlushBuffers
+│  └─ factory/       # LoggerFactory
+└─ infrastructure/   # Implementaciones concretas
+   └─ services/      # DataSourceService (composite)
+```
+
+### Casos de Uso Principales
+
+- **[`SaveLogUseCase`](src/application/use-cases/save-log.use-case.ts)** - Guarda logs aplicando filtros de nivel y PII
+- **[`GetLogsUseCase`](src/application/use-cases/get-logs.use-case.ts)** - Recupera logs con filtros
+- **[`FlushBuffersUseCase`](src/application/use-cases/flush-buffers.use-case.ts)** - Vacía buffers de datasources
+
+### Servicios de Dominio
+
+- **[`PiiRedactor`](src/domain/services/pii-redactor.service.ts)** - Enmascara datos sensibles
+- **[`MessageNormalizer`](src/domain/services/message-normalizer.service.ts)** - Normaliza mensajes de log
+- **[`LogLevelService`](src/domain/services/log-level.service.ts)** - Maneja niveles de log
+
+## 🔌 Plugins Disponibles
+
+| Plugin                           | Descripción                | NPM                                                             |
+| -------------------------------- | -------------------------- | --------------------------------------------------------------- |
+| `@jmlq/logger-plugin-fs`         | Persistencia en archivos   | [npm](https://npmjs.com/package/@jmlq/logger-plugin-fs)         |
+| `@jmlq/logger-plugin-mongo`      | Persistencia en MongoDB    | [npm](https://npmjs.com/package/@jmlq/logger-plugin-mongo)      |
+| `@jmlq/logger-plugin-postgresql` | Persistencia en PostgreSQL | [npm](https://npmjs.com/package/@jmlq/logger-plugin-postgresql) |
+
+## 📄 Más Información
+
+- **[Arquitectura Detallada](./architecture.md)** - Documentación técnica completa
+- **[Guía de Instalación](./install.md)** - Configuración paso a paso
+- **[Ejemplos](./examples/)** - Códigos de ejemplo funcionales
+
+## 📝 Licencia
+
+MIT © Mauricio Lahuasi

package/architecture.md

@@ -0,0 +1,171 @@
+# Arquitectura del Paquete @jmlq/logger
+
+## Visión General
+
+El paquete `@jmlq/logger` está diseñado siguiendo los principios de **Arquitectura Limpia**, proporcionando un sistema de logging extensible y desacoplado que permite registrar logs en múltiples destinos mediante plugins y soporta enmascarado de datos sensibles (PII - Personally Identifiable Information).
+
+## Principios de Diseño
+
+- **Separación de responsabilidades**: Cada capa tiene una responsabilidad específica
+- **Inversión de dependencias**: Las capas internas no dependen de las externas
+- **Extensibilidad**: Sistema de plugins para diferentes adaptadores de persistencia
+- **Testabilidad**: Arquitectura que facilita la creación de pruebas unitarias
+- **Configurabilidad**: Múltiples opciones de configuración mediante variables de entorno
+
+## Estructura de Capas
+
+### 📁 Domain (Capa de Dominio)
+
+La capa más interna que contiene la lógica de negocio pura, sin dependencias externas.
+
+#### **Entities & Value Objects**
+
+- [`LogLevelVo`](src/domain/value-objects/log-level.vo.ts): Objeto de valor que representa los niveles de log
+
+#### **Ports (Interfaces)**
+
+- [`ILoggerPort`](src/domain/ports/logger.port.ts): Contrato principal del logger
+- [`ILogDatasourcePort`](src/domain/ports/log-datasource.port.ts): Contrato para fuentes de datos
+- [`ILoggerServicePort`](src/domain/ports/logger-service.port.ts): Contrato para servicios de logging
+- [`IPiiRedactorPort`](src/domain/ports/pii-redactor.port.ts): Contrato para enmascarado PII
+- [`ILoggerFactoryConfigPort`](src/domain/ports/logger-factory-config.port.ts): Contrato de configuración del factory
+
+#### **Services (Servicios de Dominio)**
+
+- [`LogLevelService`](src/domain/services/log-level.service.ts): Lógica para manejo de niveles de log
+- [`MessageNormalizerService`](src/domain/services/message-normalizer.service.ts): Normalización de mensajes
+- [`PiiPatternService`](src/domain/services/pii-pattern.service.ts): Gestión de patrones PII
+- [`PiiRedactorService`](src/domain/services/pii-redactor.service.ts): Enmascarado de datos sensibles
+
+#### **Types & DTOs**
+
+- **Request**: [`SaveLogProps`](src/domain/request/save-log.props.ts), [`GetLogsFilterProps`](src/domain/request/get-logs-filter.props.ts), [`PiiOptionsProps`](src/domain/request/pii-options.props.ts)
+- **Response**: [`LogResponse`](src/domain/response/log.response.ts)
+- **Types**: [`LogMessageType`](src/domain/types/log-message.type.ts)
+
+### 📁 Application (Capa de Aplicación)
+
+Orquesta la lógica de negocio y coordina los casos de uso.
+
+#### **Use Cases**
+
+- [`SaveLogUseCase`](src/application/use-cases/save-log.use-case.ts): Guarda logs en los datasources configurados
+- [`GetLogsUseCase`](src/application/use-cases/get-logs.use-case.ts): Recupera logs con filtros
+- [`FlushBuffersUseCase`](src/application/use-cases/flush-buffers.use-case.ts): Vacía buffers de los datasources
+
+#### **Factory**
+
+- [`LoggerFactory`](src/application/factory/logger.factory.ts): Factory para crear instancias del logger
+
+### 📁 Infrastructure (Capa de Infraestructura)
+
+Implementaciones concretas de los contratos definidos en el dominio.
+
+#### **Services**
+
+- [`DatasourceService`](src/infrastructure/services/datasource.service.ts): Implementación del servicio de datasource
+- [`DataSourceErrorHandlerType`](src/infrastructure/services/data-source-error-handler.type.ts): Manejo de errores de datasources
+
+## Flujo de Dependencias
+
+```txt
+Infrastructure → Application → Domain
+```
+
+- **Domain**: No depende de nada, contiene la lógica de negocio pura
+- **Application**: Depende solo del Domain, orquesta los casos de uso
+- **Infrastructure**: Depende del Domain y Application, implementa los contratos
+
+## Patrones Implementados
+
+### **Factory Pattern**
+
+El [`LoggerFactory`](src/application/factory/logger.factory.ts) centraliza la creación de instancias del logger con las configuraciones apropiadas.
+
+### **Port-Adapter Pattern**
+
+Los ports en el domain definen contratos que son implementados por adaptadores en infrastructure.
+
+### **Use Case Pattern**
+
+Cada operación principal está encapsulada en un caso de uso específico con un método `execute()`.
+
+### **Dependency Injection**
+
+Las dependencias se inyectan a través de constructores, facilitando el testing y la flexibilidad.
+
+## Sistema de Plugins
+
+El logger soporta múltiples adaptadores de persistencia:
+
+- **Filesystem**: `@jmlq/logger-plugin-fs`
+- **MongoDB**: `@jmlq/logger-plugin-mongo`
+- **PostgreSQL**: `@jmlq/logger-plugin-postgresql`
+
+Cada plugin implementa los ports definidos en el domain.
+
+## Características Principales
+
+### **PII (Personally Identifiable Information)**
+
+- Enmascarado automático de datos sensibles
+- Patrones configurables y extensibles
+- Soporte para patrones por defecto y personalizados
+
+### **Niveles de Log**
+
+- debug, info, warn, error, fatal
+- Configuración de nivel mínimo por entorno
+
+### **Múltiples Datasources**
+
+- Soporte simultáneo para múltiples backends
+- Configuración opcional de cada adaptador
+
+### **Configuración Flexible**
+
+- Variables de entorno
+- Configuración programática
+- Políticas de retención de datos
+
+## Ejemplo de Uso
+
+```typescript
+import { LoggerBootstrap } from "@jmlq/logger";
+
+const logger = await LoggerBootstrap.create({
+  minLevel: "debug",
+  pii: {
+    enabled: true,
+    includeDefaults: true,
+    deep: true,
+  },
+  adapters: {
+    fs: { basePath: "./logs" },
+    mongo: { url: "mongodb://localhost:27017", dbName: "logs" },
+  },
+});
+
+await logger.info("User logged in", {
+  userId: "12345",
+  email: "user@example.com",
+});
+```
+
+## Testing
+
+La arquitectura facilita el testing mediante:
+
+> - Interfaces claramente definidas
+> - Servicios desacoplados
+> - Casos de uso aislados
+> - Mocks sencillos de implementar
+
+## Consideraciones de Rendimiento
+
+> - Buffers para escritura asíncrona
+> - Políticas de rotación de archivos
+> - Retención configurable de datos
+> - Procesamiento asíncrono de logs
+
+Esta arquitectura asegura mantenibilidad, extensibilidad y testabilidad del sistema de logging, siguiendo las mejores prácticas de clean architecture.

package/dist/application/factory/index.d.ts

@@ -0,0 +1 @@
+export * from "./logger.factory";

package/dist/{config → application/factory}/index.js

@@ -14,5 +14,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./interfaces"), exports);
-__exportStar(require("./types"), exports);
+__exportStar(require("./logger.factory"), exports);

package/dist/application/factory/logger.factory.d.ts

@@ -0,0 +1,10 @@
+import { ILoggerFactoryConfig, ILogger } from "../../domain/ports";
+/**
+ * Factory principal de @jmlq/logger.
+ * Se encarga de:
+ *  - Componer datasources (fan-out si hay varios)
+ *  - Construir el redactor de PII
+ *  - Instanciar y conectar los casos de uso
+ *  - Exponer un servicio de logger de alto nivel
+ */
+export declare function createLogger(config: ILoggerFactoryConfig, source?: string): ILogger;

package/dist/application/factory/logger.factory.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = createLogger;
+const value_objects_1 = require("../../domain/value-objects");
+const pii_redactor_service_1 = require("../../domain/services/pii-redactor.service");
+const services_1 = require("../../infrastructure/services");
+const use_cases_1 = require("../use-cases");
+/**
+ * Factory principal de @jmlq/logger.
+ * Se encarga de:
+ *  - Componer datasources (fan-out si hay varios)
+ *  - Construir el redactor de PII
+ *  - Instanciar y conectar los casos de uso
+ *  - Exponer un servicio de logger de alto nivel
+ */
+function createLogger(config, source = "app-logger") {
+    // 1) Normalizar config
+    const minLevel = config.minLevel ?? value_objects_1.LogLevel.INFO;
+    const datasources = Array.isArray(config.datasources)
+        ? config.datasources
+        : [config.datasources];
+    // 2) Componer datasource (si hay varios) con DataSourceService
+    const ds = datasources.length === 1
+        ? datasources[0]
+        : new services_1.DataSourceService(datasources);
+    // 3) Crear/usar redactor de PII
+    const redactor = config.redactor ?? new pii_redactor_service_1.PiiRedactor(config.redactorOptions);
+    // 4) Construir casos de uso de Application
+    const saveLogUseCase = new use_cases_1.SaveLogUseCase({
+        ds,
+        minLevel,
+        redactor,
+    });
+    const getLogsUseCase = new use_cases_1.GetLogsUseCase(ds);
+    const flushBuffersUseCase = new use_cases_1.FlushBuffersUseCase(ds);
+    // 5) Construir facade de servicio de logging
+    const service = {
+        // Método genérico de logging
+        async log(level, message, meta) {
+            await saveLogUseCase.execute("app-logger", level, message, meta);
+        },
+        // Helpers por nivel
+        trace(message, meta) {
+            return saveLogUseCase.execute(source, value_objects_1.LogLevel.TRACE, message, meta);
+        },
+        debug(message, meta) {
+            return saveLogUseCase.execute(source, value_objects_1.LogLevel.DEBUG, message, meta);
+        },
+        info(message, meta) {
+            return saveLogUseCase.execute(source, value_objects_1.LogLevel.INFO, message, meta);
+        },
+        warn(message, meta) {
+            return saveLogUseCase.execute(source, value_objects_1.LogLevel.WARN, message, meta);
+        },
+        error(message, meta) {
+            return saveLogUseCase.execute(source, value_objects_1.LogLevel.ERROR, message, meta);
+        },
+        fatal(message, meta) {
+            return saveLogUseCase.execute(source, value_objects_1.LogLevel.FATAL, message, meta);
+        },
+        // Lectura de logs con filtros
+        async getLogs(filter) {
+            return getLogsUseCase.execute(filter);
+        },
+        // Flush explícito (si el datasource lo soporta)
+        async flush() {
+            await flushBuffersUseCase.execute();
+        },
+    };
+    return service;
+}

package/dist/application/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./factory";
+export * from "./use-cases";

package/dist/{presentation → application}/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./factory"), exports);
+__exportStar(require("./use-cases"), exports);

package/dist/application/use-cases/flush-buffers.use-case.d.ts

@@ -0,0 +1,6 @@
+import { ILogDatasource } from "../../domain/ports";
+export declare class FlushBuffersUseCase {
+    private readonly ds;
+    constructor(ds: ILogDatasource);
+    execute(): Promise<void>;
+}

package/dist/application/use-cases/flush-buffers.use-case.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlushBuffersUseCase = void 0;
+class FlushBuffersUseCase {
+    constructor(ds) {
+        this.ds = ds;
+    }
+    async execute() {
+        // flush es opcional; si no está implementado, no hace nada
+        await this.ds.flush?.();
+    }
+}
+exports.FlushBuffersUseCase = FlushBuffersUseCase;

package/dist/application/use-cases/get-logs.use-case.d.ts

@@ -0,0 +1,8 @@
+import { ILogDatasource } from "../../domain/ports";
+import { LogFilterRequest } from "../../domain/request";
+import { ILogResponse } from "../../domain/response";
+export declare class GetLogsUseCase {
+    private readonly ds;
+    constructor(ds: ILogDatasource);
+    execute(filter?: LogFilterRequest): Promise<ILogResponse[]>;
+}

package/dist/application/use-cases/get-logs.use-case.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetLogsUseCase = void 0;
+class GetLogsUseCase {
+    constructor(ds) {
+        this.ds = ds;
+    }
+    async execute(filter) {
+        if (!this.ds.find)
+            return []; // si el datasource no lo soporta, retorna vacío
+        // Sanitiza límites (evita valores negativos o absurdos)
+        const safe = filter
+            ? {
+                ...filter,
+                limit: filter.limit && filter.limit > 0
+                    ? Math.min(filter.limit, 5000)
+                    : undefined,
+                offset: filter.offset && filter.offset >= 0 ? filter.offset : undefined,
+            }
+            : undefined;
+        return this.ds.find(safe);
+    }
+}
+exports.GetLogsUseCase = GetLogsUseCase;

package/dist/application/use-cases/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./save-log.use-case";
+export * from "./get-logs.use-case";
+export * from "./flush-buffers.use-case";

package/dist/application/use-cases/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./save-log.use-case"), exports);
+__exportStar(require("./get-logs.use-case"), exports);
+__exportStar(require("./flush-buffers.use-case"), exports);

package/dist/application/use-cases/save-log/index.d.ts

@@ -0,0 +1 @@
+export * from "./save-log.props";

package/dist/application/use-cases/save-log/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./save-log.props"), exports);

package/dist/application/use-cases/save-log/save-log.props.d.ts

@@ -0,0 +1,7 @@
+import { LogLevel } from "../../../domain/value-objects";
+import { ILogDatasource, IPiiRedactor } from "../../../domain/ports";
+export interface SaveLogDependencies {
+    ds: ILogDatasource;
+    minLevel: LogLevel;
+    redactor: IPiiRedactor;
+}

package/dist/{config/interfaces/index.js → application/use-cases/save-log/save-log.props.js}

@@ -1,3 +1,2 @@
 "use strict";
-// ---- Contratos ----
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/application/use-cases/save-log.use-case.d.ts

@@ -0,0 +1,8 @@
+import { LogMessage } from "../../domain/types";
+import { LogLevel } from "../../domain/value-objects";
+import { SaveLogDependencies } from "./save-log";
+export declare class SaveLogUseCase {
+    private readonly props;
+    constructor(props: SaveLogDependencies);
+    execute(source: string, level: LogLevel, message: LogMessage, meta?: unknown): Promise<void>;
+}