@seidor-cloud-produtos/orbit-backend-lib 2.0.138 → 2.1.0

package/dist/clean-arch/application/cache/cache.d.ts

@@ -1,31 +1,63 @@
 import { Logger } from '../logger';
 import { CacheClient } from './client';
+/**
+ * Opcoes por metodo (sobrescrevem CacheOptions).
+ */
 export type MethodOptions = {
     throwOnError?: boolean;
 };
+/**
+ * Opcoes globais do cache.
+ * - throwOnError: quando true, propaga erros.
+ * - contingencyClients: lista de clientes alternativos para fallback.
+ */
 export type CacheOptions = {
     throwOnError?: boolean;
     contingencyClients?: CacheClient[];
 };
+/**
+ * Camada de cache padrao da lib.
+ * Responsavel por:
+ * - controlar TTL padrao
+ * - serializacao JSON
+ * - fallback entre clientes
+ */
 export declare abstract class Cache {
     protected logger: Logger;
     protected abstract client: CacheClient;
     protected elegibleClients: CacheClient[];
+    /** TTL padrao (segundos). */
     protected DEFAULT_EXPIRATION_SECONDS: number;
     private options?;
     constructor(options?: CacheOptions, logger?: Logger);
     private setElegibleClients;
     private setOptions;
     private setRunningClient;
+    /** Inicia o cliente de cache. */
     start(options?: MethodOptions): Promise<void>;
+    /** Busca um valor do cache. */
     get(keyCache: string, options?: MethodOptions): Promise<any>;
+    /** Grava um valor no cache com TTL (segundos). */
     set(keyCache: string, data: any, expiration?: number, options?: MethodOptions): Promise<void>;
+    /** Remove uma chave do cache. */
     del(keyCache: string, options?: MethodOptions): Promise<void>;
+    /** Lista chaves; o pattern varia por cliente. */
     getKeys(pattern?: string, options?: MethodOptions): Promise<string[] | null>;
+    /** Remove varias chaves de uma vez. */
     delBatch(patterns: string[], options?: MethodOptions): Promise<void>;
+    /** Limpa o banco/instancia de cache. */
     flush(): Promise<void>;
+    /**
+     * Health-check do cache.
+     * - se falhar, tenta alternar para um cliente elegivel
+     */
     isRunning(options?: MethodOptions, isContingency?: boolean): Promise<boolean>;
+    /** Encerra o cliente de cache. */
     close(options?: MethodOptions): Promise<void>;
+    /** Padroniza o log/propagacao de erros. */
     protected handleException(e: Error): Promise<void>;
+    /**
+     * Busca do cache e, se nao existir, executa a promise e grava o resultado.
+     */
     getOrFetchAndCache<T>(keyCache: string, expiration: number | undefined, promise: () => Promise<T>, options?: MethodOptions): Promise<T | undefined>;
 }

package/dist/clean-arch/application/cache/cache.js

@@ -2,9 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Cache = void 0;
 const env_1 = require("../../infra/environment/env");
+/**
+ * Camada de cache padrao da lib.
+ * Responsavel por:
+ * - controlar TTL padrao
+ * - serializacao JSON
+ * - fallback entre clientes
+ */
 class Cache {
     logger;
     elegibleClients;
+    /** TTL padrao (segundos). */
     DEFAULT_EXPIRATION_SECONDS = env_1.env?.DEFAULT_CACHE_EXPIRATION || 360;
     options;
     constructor(options, logger = console) {
@@ -51,6 +59,7 @@ class Cache {
         this.logger.warn(`Changed cache client to ${this.client.constructor.name}`);
         return this;
     }
+    /** Inicia o cliente de cache. */
     async start(options) {
         try {
             await this.client.start();
@@ -66,6 +75,7 @@ class Cache {
         }
         this.logger.info('💾 Cache Connected');
     }
+    /** Busca um valor do cache. */
     async get(keyCache, options) {
         try {
             const dataFromCache = await this.client.get(keyCache);
@@ -78,6 +88,7 @@ class Cache {
             return null;
         }
     }
+    /** Grava um valor no cache com TTL (segundos). */
     async set(keyCache, data, expiration = this.DEFAULT_EXPIRATION_SECONDS, options) {
         try {
             return await this.client.set(keyCache, JSON.stringify(data), expiration);
@@ -89,6 +100,7 @@ class Cache {
             return;
         }
     }
+    /** Remove uma chave do cache. */
     async del(keyCache, options) {
         try {
             return await this.client.del(keyCache);
@@ -100,6 +112,7 @@ class Cache {
             return;
         }
     }
+    /** Lista chaves; o pattern varia por cliente. */
     async getKeys(pattern, options) {
         try {
             return await this.client.getKeys(pattern);
@@ -111,6 +124,7 @@ class Cache {
             return null;
         }
     }
+    /** Remove varias chaves de uma vez. */
     async delBatch(patterns, options) {
         try {
             return await this.client.delBatch(patterns);
@@ -122,6 +136,7 @@ class Cache {
             return;
         }
     }
+    /** Limpa o banco/instancia de cache. */
     async flush() {
         try {
             return await this.client.flush();
@@ -130,6 +145,10 @@ class Cache {
             await this.handleException(e);
         }
     }
+    /**
+     * Health-check do cache.
+     * - se falhar, tenta alternar para um cliente elegivel
+     */
     async isRunning(options, isContingency = false) {
         let isRunning = false;
         try {
@@ -146,6 +165,7 @@ class Cache {
         }
         return isRunning;
     }
+    /** Encerra o cliente de cache. */
     async close(options) {
         this.logger.info('💾 Cache closed');
         try {
@@ -158,10 +178,14 @@ class Cache {
             return;
         }
     }
+    /** Padroniza o log/propagacao de erros. */
     async handleException(e) {
         this.logger.error(JSON.stringify(e));
         throw e;
     }
+    /**
+     * Busca do cache e, se nao existir, executa a promise e grava o resultado.
+     */
     async getOrFetchAndCache(keyCache, expiration = this.DEFAULT_EXPIRATION_SECONDS, promise, options) {
         let data = await this.get(keyCache, options);
         if (!data) {

package/dist/clean-arch/application/cache/cache.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clean-arch/application/cache/cache.spec.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cache_1 = require("./cache");
+const client_1 = require("./client");
+class MemoryCacheClient extends client_1.CacheClient {
+    startMock = vi.fn().mockResolvedValue(undefined);
+    closeMock = vi.fn().mockResolvedValue(undefined);
+    getMock = vi.fn();
+    setMock = vi.fn().mockResolvedValue(undefined);
+    delMock = vi.fn().mockResolvedValue(undefined);
+    delBatchMock = vi.fn().mockResolvedValue(undefined);
+    getKeysMock = vi.fn().mockResolvedValue([]);
+    flushMock = vi.fn().mockResolvedValue(undefined);
+    async start() {
+        await this.startMock();
+    }
+    async close() {
+        await this.closeMock();
+    }
+    async get(keyCache) {
+        return await this.getMock(keyCache);
+    }
+    async set(keyCache, data, expiration) {
+        await this.setMock(keyCache, data, expiration);
+    }
+    async del(keyCache) {
+        await this.delMock(keyCache);
+    }
+    async delBatch(keyCache) {
+        await this.delBatchMock(keyCache);
+    }
+    async getKeys(pattern) {
+        return await this.getKeysMock(pattern);
+    }
+    async flush() {
+        await this.flushMock();
+    }
+}
+class TestCache extends cache_1.Cache {
+    client = new MemoryCacheClient();
+    get currentClient() {
+        return this.client;
+    }
+}
+const createLogger = () => ({
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+});
+describe('Cache base', () => {
+    it('should perform the happy path operations', async () => {
+        const logger = createLogger();
+        const cache = new TestCache(undefined, logger);
+        cache.currentClient.getMock.mockResolvedValueOnce({ id: '1' });
+        cache.currentClient.getKeysMock.mockResolvedValueOnce(['cache:key']);
+        await cache.start();
+        await expect(cache.get('cache:key')).resolves.toEqual({ id: '1' });
+        await expect(cache.set('cache:key', { id: '1' }, 10)).resolves.toBeUndefined();
+        await expect(cache.del('cache:key')).resolves.toBeUndefined();
+        await expect(cache.getKeys('cache:*')).resolves.toEqual(['cache:key']);
+        await expect(cache.delBatch(['cache:key'])).resolves.toBeUndefined();
+        await expect(cache.flush()).resolves.toBeUndefined();
+        cache.currentClient.getMock.mockResolvedValueOnce({ ping: true });
+        await expect(cache.isRunning()).resolves.toBe(true);
+        await cache.close();
+        expect(cache.currentClient.startMock).toHaveBeenCalledTimes(1);
+        expect(cache.currentClient.setMock).toHaveBeenNthCalledWith(1, 'cache:key', JSON.stringify({ id: '1' }), 10);
+        expect(cache.currentClient.delMock).toHaveBeenCalledWith('cache:key');
+        expect(cache.currentClient.delBatchMock).toHaveBeenCalledWith([
+            'cache:key',
+        ]);
+        expect(cache.currentClient.flushMock).toHaveBeenCalledTimes(1);
+        expect(cache.currentClient.closeMock).toHaveBeenCalledTimes(1);
+        expect(logger.info).toHaveBeenCalledWith('💾 Cache Connected');
+        expect(logger.info).toHaveBeenCalledWith('💾 Cache closed');
+    });
+    it('should fetch, cache and reuse values', async () => {
+        const cache = new TestCache();
+        const promise = vi.fn().mockResolvedValue({ id: '1' });
+        cache.currentClient.getMock
+            .mockResolvedValueOnce(null)
+            .mockResolvedValueOnce({ id: '1' });
+        await expect(cache.getOrFetchAndCache('cache:key', 15, promise)).resolves.toEqual({ id: '1' });
+        await expect(cache.getOrFetchAndCache('cache:key', 15, promise)).resolves.toEqual({ id: '1' });
+        expect(promise).toHaveBeenCalledTimes(1);
+        expect(cache.currentClient.setMock).toHaveBeenCalledWith('cache:key', JSON.stringify({ id: '1' }), 15);
+    });
+    it('should return safe fallbacks when operations fail without throwOnError', async () => {
+        const cache = new TestCache();
+        cache.currentClient.getMock.mockRejectedValue(new Error('get failed'));
+        cache.currentClient.setMock.mockRejectedValue(new Error('set failed'));
+        cache.currentClient.delMock.mockRejectedValue(new Error('del failed'));
+        cache.currentClient.getKeysMock.mockRejectedValue(new Error('keys failed'));
+        cache.currentClient.delBatchMock.mockRejectedValue(new Error('batch failed'));
+        cache.currentClient.closeMock.mockRejectedValue(new Error('close failed'));
+        cache.currentClient.getMock.mockResolvedValueOnce(false);
+        await expect(cache.get('cache:key')).resolves.toBeNull();
+        await expect(cache.set('cache:key', { id: '1' })).resolves.toBeUndefined();
+        await expect(cache.del('cache:key')).resolves.toBeUndefined();
+        await expect(cache.getKeys('cache:*')).resolves.toBeNull();
+        await expect(cache.delBatch(['cache:key'])).resolves.toBeUndefined();
+        await expect(cache.close()).resolves.toBeUndefined();
+    });
+    it('should throw when throwOnError is enabled', async () => {
+        const logger = createLogger();
+        const cache = new TestCache(undefined, logger);
+        cache.currentClient.getMock.mockRejectedValue(new Error('get failed'));
+        await expect(cache.get('cache:key', { throwOnError: true })).rejects.toThrow('get failed');
+        expect(logger.error).toHaveBeenCalledWith(JSON.stringify(new Error('get failed')));
+    });
+    it('should switch to a running contingency client', async () => {
+        const logger = createLogger();
+        const cache = new TestCache(undefined, logger);
+        const primary = cache.currentClient;
+        const contingency = new MemoryCacheClient();
+        primary.getMock.mockResolvedValue(false);
+        contingency.getMock.mockResolvedValue({ ping: true });
+        cache.elegibleClients = [contingency, primary];
+        await expect(cache.isRunning()).resolves.toBe(true);
+        expect(primary.closeMock).toHaveBeenCalledTimes(1);
+        expect(logger.warn).toHaveBeenCalledWith('Changed cache client to MemoryCacheClient');
+        expect(cache.client).toBe(contingency);
+    });
+    it('should tolerate failed start with a single eligible client', async () => {
+        const logger = createLogger();
+        const cache = new TestCache(undefined, logger);
+        cache.options = { throwOnError: false };
+        cache.elegibleClients = [cache.currentClient];
+        cache.currentClient.startMock.mockRejectedValueOnce(new Error('start failed'));
+        await expect(cache.start()).resolves.toBeUndefined();
+        expect(logger.warn).not.toHaveBeenCalled();
+    });
+    it('should ignore contingency discovery errors while switching cache clients', async () => {
+        const logger = createLogger();
+        const cache = new TestCache(undefined, logger);
+        const primary = cache.currentClient;
+        const brokenContingency = new MemoryCacheClient();
+        const healthyContingency = new MemoryCacheClient();
+        cache.options = { throwOnError: false };
+        cache.elegibleClients = [
+            brokenContingency,
+            healthyContingency,
+            primary,
+        ];
+        primary.startMock.mockRejectedValueOnce(new Error('primary start failed'));
+        primary.closeMock.mockRejectedValueOnce(new Error('primary close failed'));
+        brokenContingency.startMock.mockRejectedValueOnce(new Error('contingency start failed'));
+        healthyContingency.getMock.mockResolvedValue({ ping: true });
+        await expect(cache.start()).resolves.toBeUndefined();
+        expect(cache.client).toBe(healthyContingency);
+        expect(brokenContingency.startMock).toHaveBeenCalledTimes(1);
+        expect(brokenContingency.closeMock).toHaveBeenCalledTimes(1);
+        expect(primary.closeMock).toHaveBeenCalledTimes(1);
+        expect(logger.warn).toHaveBeenCalledWith('Changed cache client to MemoryCacheClient');
+    });
+    it('should return false when health checks fail without throwOnError', async () => {
+        const logger = createLogger();
+        const cache = new TestCache(undefined, logger);
+        cache.options = { throwOnError: false };
+        cache.elegibleClients = [cache.currentClient];
+        cache.currentClient.setMock.mockRejectedValue(new Error('ping failed'));
+        await expect(cache.isRunning()).resolves.toBe(false);
+    });
+    it('should throw when close fails and throwOnError is enabled', async () => {
+        const logger = createLogger();
+        const cache = new TestCache(undefined, logger);
+        cache.currentClient.closeMock.mockRejectedValue(new Error('close failed'));
+        await expect(cache.close({ throwOnError: true })).rejects.toThrowError('close failed');
+        expect(logger.error).toHaveBeenCalledWith(JSON.stringify(new Error('close failed')));
+    });
+    it('should verify if a cache client is running with a ping key', async () => {
+        const client = new MemoryCacheClient({ timeout: 5 });
+        client.getMock.mockResolvedValue({ ping: true });
+        await expect(client.isRunning()).resolves.toBe(true);
+        expect(client.setMock).toHaveBeenCalledWith(expect.any(String), JSON.stringify({ ping: true }), 5);
+    });
+});

package/dist/clean-arch/application/cache/client.d.ts

@@ -1,16 +1,39 @@
+/**
+ * Opcoes basicas para clientes de cache.
+ * - timeout: segundos usados como timeout de operacoes e ping.
+ */
 export interface CacheClientOptions {
     timeout?: number;
 }
+/**
+ * Contrato minimo de um cliente de cache.
+ * Cada implementacao deve cuidar de:
+ * - conexao (start/close)
+ * - operacoes basicas (get/set/del/getKeys/flush)
+ */
 export declare abstract class CacheClient {
     protected connection?: CacheClientOptions | undefined;
     constructor(connection?: CacheClientOptions | undefined);
+    /** Inicializa o cliente/conexao. */
     abstract start(): Promise<void>;
+    /** Encerra o cliente/conexao. */
     abstract close(): Promise<void>;
+    /** Recupera um valor pelo nome da chave. */
     abstract get(keyCache: string): Promise<any>;
+    /** Grava um valor com TTL opcional (segundos). */
     abstract set(keyCache: string, data: any, expiration?: number): Promise<void>;
+    /** Remove uma chave. */
     abstract del(keyCache: string): Promise<void>;
+    /** Remove varias chaves. */
     abstract delBatch(keyCache: string[]): Promise<void>;
+    /** Lista chaves; o pattern depende do cliente. */
     abstract getKeys(pattern?: string): Promise<string[] | null>;
+    /** Limpa o banco/instancia. */
     abstract flush(): Promise<void>;
+    /**
+     * Health-check simples:
+     * - grava um ping
+     * - le de volta e valida
+     */
     isRunning(): Promise<any>;
 }

package/dist/clean-arch/application/cache/client.js

@@ -2,11 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacheClient = void 0;
 const unique_entity_id_1 = require("../../domain/entities/unique-entity-id");
+/**
+ * Contrato minimo de um cliente de cache.
+ * Cada implementacao deve cuidar de:
+ * - conexao (start/close)
+ * - operacoes basicas (get/set/del/getKeys/flush)
+ */
 class CacheClient {
     connection;
     constructor(connection) {
         this.connection = connection;
     }
+    /**
+     * Health-check simples:
+     * - grava um ping
+     * - le de volta e valida
+     */
     async isRunning() {
         const key = new unique_entity_id_1.UniqueEntityId().toValue();
         await this.set(key, JSON.stringify({ ping: true }), this.connection?.timeout || 60);

package/dist/clean-arch/application/consistency-event-dispatcher/consistency-event-dispatcher.d.ts

@@ -0,0 +1,9 @@
+import { Entity } from '../../domain/entities/entity';
+import ConsistencyEvent from '../../domain/events/consistency-event/consistency-event';
+import { EventsName } from '../../domain/events/consistency-event/events-enum';
+import { AuthorizerHeaders } from '../../infra/http/handle-authorizer-headers';
+export declare abstract class ConsistencyEventDispatcher {
+    dispatch(entity: Entity<any>, authorizerHeaders: AuthorizerHeaders, eventName: EventsName): Promise<void>;
+    dispatchBatch(entities: Entity<any>[], authorizerHeaders: AuthorizerHeaders, eventName: EventsName): Promise<void>;
+    abstract publish(event: ConsistencyEvent): Promise<void>;
+}

package/dist/clean-arch/application/consistency-event-dispatcher/consistency-event-dispatcher.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsistencyEventDispatcher = void 0;
+const tslib_1 = require("tslib");
+const consistency_event_1 = tslib_1.__importDefault(require("../../domain/events/consistency-event/consistency-event"));
+class ConsistencyEventDispatcher {
+    async dispatch(entity, authorizerHeaders, eventName) {
+        try {
+            const event = new consistency_event_1.default([entity], authorizerHeaders, eventName);
+            await this.publish(event);
+        }
+        catch (error) {
+            console.error(`Failed to dispatch consistency event: ${error}`);
+        }
+    }
+    async dispatchBatch(entities, authorizerHeaders, eventName) {
+        try {
+            const event = new consistency_event_1.default(entities, authorizerHeaders, eventName);
+            await this.publish(event);
+        }
+        catch (error) {
+            console.error(`Failed to dispatch batch consistency events: ${error}`);
+        }
+    }
+}
+exports.ConsistencyEventDispatcher = ConsistencyEventDispatcher;

package/dist/clean-arch/application/logger/base-audit-logger.d.ts

@@ -0,0 +1,10 @@
+import { AuthorizerHeaders } from '../../infra/http/handle-authorizer-headers';
+import LoggerGateway, { Trace } from '.';
+import { LogOrbitParams } from '../../infra/logger/logger-orbit';
+export declare abstract class BaseAuditLogger {
+    protected readonly gateway: LoggerGateway;
+    protected defaultExpirationHours: number;
+    constructor(gateway: LoggerGateway);
+    protected buildParams(type: string, authorizerHeaders: AuthorizerHeaders, trace: Trace): LogOrbitParams;
+    protected info(payload: any, params: LogOrbitParams): Promise<void>;
+}

package/dist/clean-arch/application/logger/base-audit-logger.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAuditLogger = void 0;
+const _1 = require(".");
+const FIVE_YEARS_IN_HOURS = 24 * 365 * 5;
+class BaseAuditLogger {
+    gateway;
+    defaultExpirationHours = FIVE_YEARS_IN_HOURS;
+    constructor(gateway) {
+        this.gateway = gateway;
+    }
+    buildParams(type, authorizerHeaders, trace) {
+        trace.ids.push(authorizerHeaders.traceId);
+        return {
+            type,
+            trace,
+            actor: authorizerHeaders.entityId,
+            tenantId: authorizerHeaders.tenantId,
+            actorType: _1.ActorEnum.USER,
+            category: _1.CategoryEnum.BUSINESS,
+            expirationHours: this.defaultExpirationHours,
+        };
+    }
+    async info(payload, params) {
+        return await this.gateway.info({ payload }, params);
+    }
+}
+exports.BaseAuditLogger = BaseAuditLogger;

package/dist/clean-arch/application/logger/index.d.ts

@@ -1,51 +1,139 @@
 import { LOG_LEVEL } from '../../infra/environment/types';
 import { Cache } from '../cache/cache';
+export interface Trace {
+    mainId?: string;
+    ids: string[];
+}
+/**
+ * Identifica o tipo de ator que originou o log.
+ */
 export declare enum ActorEnum {
     SYSTEM = "system",
     USER = "user"
 }
+/**
+ * Categoriza o log em negócio ou técnico.
+ */
 export declare enum CategoryEnum {
     BUSINESS = "business",
     TECHNICAL = "technical"
 }
+/**
+ * Propriedades obrigatórias após a construção do log.
+ */
 export interface LogProperties {
     level: LOG_LEVEL;
     actor: string;
     type: string;
     dateTime: Date;
 }
+/**
+ * Propriedades mínimas de entrada para logar.
+ */
 export interface LogPropertiesInput {
     level: LOG_LEVEL;
 }
+/**
+ * Parâmetros padrão usados para construir propriedades de log.
+ */
 export interface LogParams {
     actor: string;
     type: string;
 }
+export type LogParamsInput = Partial<LogParams>;
+/**
+ * Opções de comportamento do logger.
+ */
 export interface LogOptions {
+    /**
+     * Quando `true`, assume que o último argumento do log é `params` adicionais.
+     */
     lastArgIsParams?: boolean;
 }
+/**
+ * Interface mínima de um logger.
+ */
 export interface Logger {
     info: (...input: any[]) => Promise<void> | void;
     warn: (...input: any[]) => Promise<void> | void;
     error: (...input: any[]) => Promise<void> | void;
     debug: (...input: any[]) => Promise<void> | void;
 }
+export type LoggerGatewayProps = {
+    cache?: Cache;
+    options?: LogOptions;
+    params?: LogParamsInput;
+};
+/**
+ * Classe base para loggers.
+ *
+ * Responsável por:
+ * - Montar propriedades padrão (`actor`, `type`, `level`, `dateTime`).
+ * - Aplicar filtros por nível com apoio opcional de cache.
+ * - Delegar o envio para a implementação concreta (`register`).
+ */
 export default abstract class LoggerGateway implements Logger {
-    protected cache?: Cache | undefined;
-    protected options?: LogOptions | undefined;
-    protected params?: LogParams | undefined;
-    constructor(cache?: Cache | undefined, options?: LogOptions | undefined, params?: LogParams | undefined);
+    protected cache?: Cache;
+    protected options?: LogOptions;
+    protected params?: LogParamsInput;
+    constructor(props?: LoggerGatewayProps);
     private static cacheKey;
+    /**
+     * Loga com nível `info`.
+     */
     info(...input: any[]): Promise<void>;
+    /**
+     * Loga com nível `warn`.
+     */
     warn(...input: any[]): Promise<void>;
+    /**
+     * Loga com nível `error`.
+     */
     error(...input: any[]): Promise<void>;
+    /**
+     * Loga com nível `debug`.
+     */
     debug(...input: any[]): Promise<void>;
+    /**
+     * Fluxo principal de logging.
+     *
+     * - Extrai params extras quando `lastArgIsParams` estiver habilitado.
+     * - Monta propriedades finais.
+     * - Checa se deve logar (nível/cache).
+     * - Delegada envio para `register`.
+     */
     log(props: LogPropertiesInput, dataToLog: any): Promise<void>;
+    /**
+     * Implementação concreta deve persistir/enviar o log.
+     */
     protected abstract register(props: LogProperties, dataToLog: any, params?: LogParams): Promise<void> | void;
+    /**
+     * Constrói a lista de níveis aceitos com base no nível configurado.
+     */
     private static buildAcceptLogLevelValues;
+    /**
+     * Decide se o log deve ser emitido.
+     *
+     * - `error` sempre é emitido.
+     * - Sem cache, sempre emite.
+     * - Com cache, consulta o nível permitido por tipo/actor.
+     */
     protected isToLog(props: LogProperties, dataToLog: any): Promise<boolean>;
-    protected buildProps(props?: LogPropertiesInput, params?: LogParams): LogProperties;
-    protected buildDefaultProps(params?: LogParams): LogProperties;
+    /**
+     * Monta as propriedades finais do log.
+     */
+    protected buildProps(props?: LogPropertiesInput, params?: LogParamsInput): LogProperties;
+    /**
+     * Monta propriedades padrão.
+     */
+    protected buildDefaultProps(params?: LogParamsInput): LogProperties;
+    /**
+     * Define o nível de log no cache para um filtro (type/actor).
+     *
+     * @param level Nível mínimo a ser aceito.
+     * @param filter Filtro de log por tipo e ator.
+     * @param ttl Tempo em segundos (default 4 dias).
+     */
     setLevel(level: LOG_LEVEL, filter: {
         logType: string;
         logActor: string;